{ "openapi": "3.1.0", "info": { "title": "PollYou Public API", "version": "1.0.0", "description": "Public REST API v1 of PollYou. Authenticate with an API key of your organization: `Authorization: Bearer py_live_…`. Scopes: surveys:read, surveys:write, responses:read, responses:write, analytics:read. Rate limit per key; see the `X-RateLimit-*` headers." }, "servers": [ { "url": "/" } ], "paths": { "/api/v1/responses/{id}": { "get": { "operationId": "api_v1responses_id_get", "tags": [ "Responses" ], "responses": { "200": { "description": "V1Response resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Response" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "401": { "description": "Missing, invalid, expired or revoked API key" }, "403": { "description": "The API key lacks the required scope, or X-Organization-Id names another organization" }, "429": { "description": "Rate limit of the API key exceeded (see Retry-After)" } }, "summary": "Get a response with all answers (scope responses:read)", "description": "Get a response with all answers (scope responses:read)", "parameters": [ { "name": "id", "in": "path", "description": "V1Response identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false } ], "security": [ { "apiKey": [] } ] }, "delete": { "operationId": "api_v1responses_id_delete", "tags": [ "Responses" ], "responses": { "204": { "description": "V1Response resource deleted" }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "401": { "description": "Missing, invalid, expired or revoked API key" }, "403": { "description": "The API key lacks the required scope, or X-Organization-Id names another organization" }, "429": { "description": "Rate limit of the API key exceeded (see Retry-After)" } }, "summary": "Delete a response permanently (scope responses:write)", "description": "For example for data subject requests. Removes the response with its answers; aggregates are recomputed. Audit-logged (`response.deleted`).", "parameters": [ { "name": "id", "in": "path", "description": "V1Response identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false } ], "security": [ { "apiKey": [] } ] } }, "/api/v1/surveys": { "get": { "operationId": "api_v1surveys_get", "tags": [ "Surveys" ], "responses": { "200": { "description": "V1Survey resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Survey.V1SurveyPage" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "401": { "description": "Missing, invalid, expired or revoked API key" }, "403": { "description": "The API key lacks the required scope, or X-Organization-Id names another organization" }, "429": { "description": "Rate limit of the API key exceeded (see Retry-After)" } }, "summary": "List surveys (scope surveys:read)", "description": "Most recently updated first. Archived surveys only appear with `status=archived`.", "parameters": [ { "name": "status", "in": "query", "description": "Only surveys with this status", "required": false, "deprecated": false, "schema": { "type": "string", "enum": [ "draft", "scheduled", "live", "closed", "archived" ] }, "style": "form", "explode": true }, { "name": "type", "in": "query", "description": "Only polls or only surveys", "required": false, "deprecated": false, "schema": { "type": "string", "enum": [ "poll", "survey" ] }, "style": "form", "explode": true }, { "name": "page", "in": "query", "description": "Page number (1-based)", "required": false, "deprecated": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "style": "form", "explode": true } ], "security": [ { "apiKey": [] } ] }, "post": { "operationId": "api_v1surveys_post", "tags": [ "Surveys" ], "responses": { "201": { "description": "V1Survey resource created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Survey" } } }, "links": {} }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "422": { "description": "An error occurred", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } } }, "links": {} }, "401": { "description": "Missing, invalid, expired or revoked API key" }, "403": { "description": "The API key lacks the required scope, or X-Organization-Id names another organization" }, "429": { "description": "Rate limit of the API key exceeded (see Retry-After)" } }, "summary": "Create a draft (scope surveys:write)", "description": "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.", "parameters": [], "requestBody": { "description": "The new V1Survey resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Survey.V1SurveyCreateInput" } } }, "required": true }, "security": [ { "apiKey": [] } ] } }, "/api/v1/surveys/{id}": { "get": { "operationId": "api_v1surveys_id_get", "tags": [ "Surveys" ], "responses": { "200": { "description": "V1Survey resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Survey" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "401": { "description": "Missing, invalid, expired or revoked API key" }, "403": { "description": "The API key lacks the required scope, or X-Organization-Id names another organization" }, "429": { "description": "Rate limit of the API key exceeded (see Retry-After)" } }, "summary": "Get a survey with its structure (scope surveys:read)", "description": "Get a survey with its structure (scope surveys:read)", "parameters": [ { "name": "id", "in": "path", "description": "V1Survey identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false } ], "security": [ { "apiKey": [] } ] }, "patch": { "operationId": "api_v1surveys_id_patch", "tags": [ "Surveys" ], "responses": { "200": { "description": "V1Survey resource updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Survey" } } }, "links": {} }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "422": { "description": "An error occurred", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } } }, "links": {} }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "401": { "description": "Missing, invalid, expired or revoked API key" }, "403": { "description": "The API key lacks the required scope, or X-Organization-Id names another organization" }, "429": { "description": "Rate limit of the API key exceeded (see Retry-After)" } }, "summary": "Change title or description (scope surveys:write)", "description": "Merge patch (`application/merge-patch+json`): omitted fields stay unchanged. Changes the draft; respondents see them after the next publish. Archived surveys: 409.", "parameters": [ { "name": "id", "in": "path", "description": "V1Survey identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false } ], "requestBody": { "description": "The updated V1Survey resource", "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/V1Survey.V1SurveyUpdateInput.jsonMergePatch" } } }, "required": true }, "security": [ { "apiKey": [] } ] } }, "/api/v1/surveys/{id}/analytics": { "get": { "operationId": "api_v1surveys_idanalytics_get", "tags": [ "Analytics" ], "responses": { "200": { "description": "V1SurveyAnalytics resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1SurveyAnalytics" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "401": { "description": "Missing, invalid, expired or revoked API key" }, "403": { "description": "The API key lacks the required scope, or X-Organization-Id names another organization" }, "429": { "description": "Rate limit of the API key exceeded (see Retry-After)" } }, "summary": "Key figures and results per question (scope analytics:read)", "description": "Completed, not excluded responses in the range (default: the last 30 days including today). Same numbers as the dashboard.", "parameters": [ { "name": "from", "in": "query", "description": "Start: local date `YYYY-MM-DD` (midnight in `timezone`) or ISO 8601 date-time with offset", "required": false, "deprecated": false, "schema": { "type": "string", "example": "2026-10-01" }, "style": "form", "explode": true }, { "name": "to", "in": "query", "description": "End: local date `YYYY-MM-DD` (inclusive) or ISO 8601 date-time with offset (exclusive)", "required": false, "deprecated": false, "schema": { "type": "string", "example": "2026-10-31" }, "style": "form", "explode": true }, { "name": "timezone", "in": "query", "description": "IANA timezone of the dates (default UTC)", "required": false, "deprecated": false, "schema": { "type": "string", "example": "Europe/Berlin" }, "style": "form", "explode": true }, { "name": "id", "in": "path", "description": "V1SurveyAnalytics identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false } ], "security": [ { "apiKey": [] } ] } }, "/api/v1/surveys/{id}/close": { "post": { "operationId": "api_v1surveys_idclose_post", "tags": [ "Surveys" ], "responses": { "200": { "description": "V1Survey resource created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Survey" } } }, "links": {} }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "422": { "description": "An error occurred", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } } }, "links": {} }, "401": { "description": "Missing, invalid, expired or revoked API key" }, "403": { "description": "The API key lacks the required scope, or X-Organization-Id names another organization" }, "429": { "description": "Rate limit of the API key exceeded (see Retry-After)" } }, "summary": "Close a live or scheduled survey (scope surveys:write; 409 from other statuses)", "description": "Close a live or scheduled survey (scope surveys:write; 409 from other statuses)", "parameters": [ { "name": "id", "in": "path", "description": "V1Survey identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false } ], "security": [ { "apiKey": [] } ] } }, "/api/v1/surveys/{id}/publish": { "post": { "operationId": "api_v1surveys_idpublish_post", "tags": [ "Surveys" ], "responses": { "200": { "description": "V1Survey resource created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Survey" } } }, "links": {} }, "400": { "description": "Invalid input", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "422": { "description": "An error occurred", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ConstraintViolation" } } }, "links": {} }, "401": { "description": "Missing, invalid, expired or revoked API key" }, "403": { "description": "The API key lacks the required scope, or X-Organization-Id names another organization" }, "429": { "description": "Rate limit of the API key exceeded (see Retry-After)" } }, "summary": "Publish the draft as a new version (scope surveys:write)", "description": "The status becomes `scheduled` if the start lies in the future, otherwise `live`. 409 for archived surveys, 422 if the draft is not publishable.", "parameters": [ { "name": "id", "in": "path", "description": "V1Survey identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false } ], "security": [ { "apiKey": [] } ] } }, "/api/v1/surveys/{surveyId}/responses": { "get": { "operationId": "api_v1surveys_surveyIdresponses_get", "tags": [ "Responses" ], "responses": { "200": { "description": "V1Response resource", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Response.V1ResponsePage" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Error" } }, "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "links": {} }, "401": { "description": "Missing, invalid, expired or revoked API key" }, "403": { "description": "The API key lacks the required scope, or X-Organization-Id names another organization" }, "429": { "description": "Rate limit of the API key exceeded (see Retry-After)" } }, "summary": "List the responses of a survey (scope responses:read)", "description": "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.", "parameters": [ { "name": "status", "in": "query", "description": "completed (default), started (not completed) or all", "required": false, "deprecated": false, "schema": { "type": "string", "enum": [ "completed", "started", "all" ], "default": "completed" }, "style": "form", "explode": true }, { "name": "from", "in": "query", "description": "Start: local date `YYYY-MM-DD` (midnight in `timezone`) or ISO 8601 date-time with offset", "required": false, "deprecated": false, "schema": { "type": "string", "example": "2026-10-01" }, "style": "form", "explode": true }, { "name": "to", "in": "query", "description": "End: local date `YYYY-MM-DD` (inclusive) or ISO 8601 date-time with offset (exclusive)", "required": false, "deprecated": false, "schema": { "type": "string", "example": "2026-10-31" }, "style": "form", "explode": true }, { "name": "timezone", "in": "query", "description": "IANA timezone of the dates (default UTC)", "required": false, "deprecated": false, "schema": { "type": "string", "example": "Europe/Berlin" }, "style": "form", "explode": true }, { "name": "includeExcluded", "in": "query", "description": "Also list excluded (flagged) responses", "required": false, "deprecated": false, "schema": { "type": "boolean", "default": false }, "style": "form", "explode": true }, { "name": "limit", "in": "query", "description": "Page size", "required": false, "deprecated": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "style": "form", "explode": true }, { "name": "cursor", "in": "query", "description": "`nextCursor` of the previous page", "required": false, "deprecated": false, "schema": { "type": "string" }, "style": "form", "explode": true }, { "name": "surveyId", "in": "path", "description": "V1Response identifier", "required": true, "deprecated": false, "schema": { "type": "string" }, "style": "simple", "explode": false } ], "security": [ { "apiKey": [] } ] } } }, "components": { "schemas": { "ConstraintViolation": { "type": "object", "description": "Unprocessable entity", "properties": { "status": { "default": 422, "type": "integer" }, "violations": { "type": "array", "items": { "type": "object", "properties": { "propertyPath": { "type": "string", "description": "The property path of the violation" }, "message": { "type": "string", "description": "The message associated with the violation" }, "code": { "type": "string", "description": "The code of the violation" }, "hint": { "type": "string", "description": "An extra hint to understand the violation" }, "payload": { "type": "object", "additionalProperties": true, "description": "The serialized payload of the violation" } }, "required": [ "propertyPath", "message" ] } }, "detail": { "readOnly": true, "type": "string" }, "type": { "readOnly": true, "type": "string" }, "title": { "readOnly": true, "type": [ "string", "null" ] }, "instance": { "readOnly": true, "type": [ "string", "null" ] } } }, "Error": { "type": "object", "description": "A representation of common errors.", "properties": { "title": { "readOnly": true, "description": "A short, human-readable summary of the problem.", "type": [ "string", "null" ] }, "detail": { "readOnly": true, "description": "A human-readable explanation specific to this occurrence of the problem.", "type": [ "string", "null" ] }, "status": { "type": [ "integer", "null" ], "examples": [ 404 ], "default": 400 }, "instance": { "readOnly": true, "description": "A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.", "type": [ "string", "null" ] }, "type": { "readOnly": true, "description": "A URI reference that identifies the problem type", "type": "string" } } }, "V1Response": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "surveyId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "in_progress", "completed" ] }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "durationMs": { "type": [ "integer", "null" ] }, "channel": { "description": "How the response was collected: script, react, vue, angular, angularjs, iframe, embed, link or api", "type": "string" }, "embedId": { "type": [ "string", "null" ], "format": "uuid" }, "deviceType": { "type": [ "string", "null" ] }, "browserFamily": { "type": [ "string", "null" ] }, "osFamily": { "type": [ "string", "null" ] }, "country": { "description": "ISO 3166-1 alpha-2", "type": [ "string", "null" ] }, "locale": { "type": [ "string", "null" ] }, "referrerHost": { "type": [ "string", "null" ] }, "utm": { "type": "object", "additionalProperties": { "type": "string" } }, "meta": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "identified": { "description": "Started with a verified identity token", "type": "boolean" }, "versionNumber": { "description": "Survey version the respondent answered", "type": [ "integer", "null" ] }, "excluded": { "description": "Excluded from analytics and results (spam, test, …)", "type": "boolean" }, "answers": { "type": "array", "description": "Every question of the response's survey version in order, answered or not.", "items": { "type": "object", "required": [ "questionKey", "type", "title", "answered", "value", "displayValue", "otherText", "answeredAt" ], "properties": { "questionKey": { "type": "string" }, "type": { "type": "string", "description": "Question type, e.g. single_choice, multiple_choice, rating, nps, text" }, "title": { "type": "string" }, "answered": { "type": "boolean" }, "value": { "description": "The normalized answer as submitted (option values, number, text, …); null if unanswered" }, "displayValue": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ], "description": "Human-readable answer (option labels)" }, "otherText": { "type": [ "string", "null" ], "description": "Free text of an \"other\" option" }, "answeredAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "V1Response.V1ResponsePage": { "type": "object", "required": [ "items", "totalItems", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "status", "startedAt", "completedAt", "durationMs", "channel", "embedId", "deviceType", "browserFamily", "osFamily", "country", "locale", "referrerHost", "versionNumber", "excluded", "answers" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "in_progress", "completed" ] }, "startedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "durationMs": { "type": [ "integer", "null" ] }, "channel": { "type": "string" }, "embedId": { "type": [ "string", "null" ], "format": "uuid" }, "deviceType": { "type": [ "string", "null" ] }, "browserFamily": { "type": [ "string", "null" ] }, "osFamily": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "locale": { "type": [ "string", "null" ] }, "referrerHost": { "type": [ "string", "null" ] }, "versionNumber": { "type": [ "integer", "null" ] }, "excluded": { "type": "boolean" }, "answers": { "type": "object", "description": "question key => display value (choice labels joined with \", \", numbers for rating/NPS, booleans for yes/no)", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } } } }, "totalItems": { "description": "Number of responses matching the filter (all pages)", "type": "integer" }, "nextCursor": { "description": "Cursor of the next page; null on the last page", "type": [ "string", "null" ] } } }, "V1Survey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "publicId": { "type": "string" }, "type": { "type": "string", "enum": [ "poll", "survey" ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "live", "closed", "archived" ] }, "questionCount": { "type": "integer" }, "publishedVersion": { "type": [ "integer", "null" ] }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "hasUnpublishedChanges": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "pages": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "position", "logic", "questions" ], "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": [ "string", "null" ] }, "position": { "type": "integer" }, "logic": { "type": "array", "description": "Branching rules of the page, evaluated after it (see schemas/logic.json of @pollyou/survey-schema). Questions and pages are referenced by id.", "items": { "type": "object", "required": [ "id", "match", "conditions", "actions" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "match": { "type": "string", "enum": [ "all", "any" ] }, "conditions": { "type": "array", "items": { "type": "object", "required": [ "operator" ], "properties": { "question": { "type": "string", "description": "Question id (exclusive with meta)" }, "meta": { "type": "string", "description": "Key of the response meta (exclusive with question)" }, "operator": { "type": "string", "enum": [ "answered", "not_answered", "equals", "not_equals", "in", "not_in", "contains", "not_contains", "gt", "gte", "lt", "lte" ] }, "value": { "oneOf": [ { "type": [ "string", "number", "boolean" ] }, { "type": "array", "items": { "type": [ "string", "number", "boolean" ] } } ] } } } }, "actions": { "type": "array", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "skip_to_page", "show_question", "hide_question", "end_survey", "disqualify" ] }, "page": { "type": "string", "description": "Target page id (skip_to_page)" }, "question": { "type": "string", "description": "Target question id (show_question, hide_question)" } } } } } } }, "questions": { "type": "array", "items": { "type": "object", "required": [ "id", "key", "type", "title", "description", "required", "config", "position", "options" ], "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "type": { "type": "string", "enum": [ "single_choice", "multiple_choice", "rating", "nps", "yes_no", "dropdown", "likert", "matrix", "ranking", "text_short", "text_long", "number", "date", "email", "image_choice", "hidden" ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "required": { "type": "boolean" }, "config": { "type": "object", "additionalProperties": true, "description": "Type specific settings, see @pollyou/survey-schema (schemas/config/.json)." }, "position": { "type": "integer" }, "options": { "type": "array", "items": { "type": "object", "required": [ "id", "value", "label", "imageUrl", "isOther", "position" ], "properties": { "id": { "type": "string", "format": "uuid" }, "value": { "type": "string" }, "label": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "isOther": { "type": "boolean" }, "position": { "type": "integer" } } } } } } } } } } } }, "V1Survey.V1SurveyCreateInput": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "poll", "survey" ] }, "title": { "maxLength": 255, "default": "", "type": "string" }, "description": { "maxLength": 2000, "type": [ "string", "null" ] } }, "required": [ "title" ] }, "V1Survey.V1SurveyPage": { "type": "object", "required": [ "items", "page", "itemsPerPage", "totalItems" ], "properties": { "items": { "type": "array", "items": { "type": [ "string", "null" ] } }, "page": { "type": "integer" }, "itemsPerPage": { "type": "integer" }, "totalItems": { "description": "Number of surveys matching the filter (all pages)", "type": "integer" } } }, "V1Survey.V1SurveyUpdateInput.jsonMergePatch": { "type": "object", "properties": { "title": { "maxLength": 255, "type": [ "string", "null" ] }, "description": { "maxLength": 2000, "type": [ "string", "null" ] } } }, "V1SurveyAnalytics": { "type": "object", "properties": { "surveyId": { "type": "string", "format": "uuid" }, "meta": { "type": "object", "description": "Where the numbers come from and the resolved range (ISO 8601 in the filter timezone, `to` exclusive).", "required": [ "source", "timezone", "from", "to" ], "properties": { "source": { "type": "string", "enum": [ "rollup", "raw" ] }, "timezone": { "type": "string" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "cached": { "type": "boolean", "description": "Whether the result was served from the analytics cache (optional; results are cached for up to 10 minutes and recomputed as soon as the survey's data changes)." } } }, "overview": { "type": "object", "required": [ "impressions", "starts", "completions", "startRate", "completionRate", "averageDurationMs", "medianDurationMs" ], "properties": { "impressions": { "type": [ "integer", "null" ], "description": "Views of the survey (null where not measurable)" }, "starts": { "type": "integer" }, "completions": { "type": "integer" }, "startRate": { "type": [ "number", "null" ], "description": "starts / impressions (0-1)" }, "completionRate": { "type": [ "number", "null" ], "description": "completions / starts (0-1)" }, "averageDurationMs": { "type": [ "integer", "null" ] }, "medianDurationMs": { "type": [ "integer", "null" ] } } }, "totalResponses": { "description": "Completed responses counted in the question results", "type": "integer" }, "questions": { "type": "array", "items": { "type": "object", "required": [ "key", "type", "title", "totalAnswers" ], "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "totalAnswers": { "type": "integer", "description": "Responses with an answer to the question" }, "options": { "type": "array", "description": "single_choice, multiple_choice, yes_no, dropdown, image_choice, likert (value = scale point)", "items": { "type": "object", "required": [ "value", "label", "count", "percent", "ci" ], "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer" }, "percent": { "type": "number", "description": "count / totalAnswers in percent (1 decimal)" }, "imageUrl": { "type": [ "string", "null" ], "description": "image_choice: the option image" }, "ci": { "type": [ "object", "null" ], "description": "95 % Wilson score interval in percent (1 decimal); null without answers", "required": [ "lower", "upper" ], "properties": { "lower": { "type": "number" }, "upper": { "type": "number" } } } } } }, "distribution": { "type": "array", "description": "rating (scale min-max), nps (0-10), likert (1-points)", "items": { "type": "object", "required": [ "value", "count", "percent" ], "properties": { "value": { "type": "integer" }, "count": { "type": "integer" }, "percent": { "type": "number" } } } }, "stats": { "type": "object", "description": "rating, nps, likert, number: mean, median, sample standard deviation (2 decimals), top-2-box in percent (1 decimal; null for number)", "required": [ "mean", "median", "standardDeviation", "topTwoBox" ], "properties": { "mean": { "type": [ "number", "null" ] }, "median": { "type": [ "number", "null" ] }, "standardDeviation": { "type": [ "number", "null" ] }, "topTwoBox": { "type": [ "number", "null" ] } } }, "histogram": { "type": "array", "description": "number: equal-width bins over the answered range (whole numbers: one bin per value up to 20 values); date: bins of one day, week (from Monday), month or year depending on the span. `from` inclusive, `to` exclusive; numbers for number, YYYY-MM-DD for date", "items": { "type": "object", "required": [ "from", "to", "count" ], "properties": { "from": { "type": [ "number", "string" ] }, "to": { "type": [ "number", "string" ] }, "count": { "type": "integer" } } } }, "histogramUnit": { "type": "string", "enum": [ "value", "range", "day", "week", "month", "year" ], "description": "number: value (one bin per whole number) or range; date: the bin size" }, "range": { "type": [ "object", "null" ], "description": "number, date: smallest and largest answer (null without answers)", "required": [ "min", "max" ], "properties": { "min": { "type": [ "number", "string" ] }, "max": { "type": [ "number", "string" ] } } }, "matrix": { "type": "object", "description": "matrix: answers per row (options of the question) and column (config.columns); percent of the row's answers (1 decimal)", "required": [ "rows", "columns", "cells" ], "properties": { "rows": { "type": "array", "items": { "type": "object", "required": [ "value", "label", "answers" ], "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "answers": { "type": "integer" } } } }, "columns": { "type": "array", "items": { "type": "object", "required": [ "value", "label" ], "properties": { "value": { "type": "string" }, "label": { "type": "string" } } } }, "cells": { "type": "array", "description": "cells[row][column]", "items": { "type": "array", "items": { "type": "object", "required": [ "count", "percent" ], "properties": { "count": { "type": "integer" }, "percent": { "type": "number" } } } } } } }, "ranking": { "type": "array", "description": "ranking: per option, best Borda score first (score = sum of n - rank; averageRank 2 decimals, null if never ranked); positions[i] = rankings with the option on rank i + 1", "items": { "type": "object", "required": [ "value", "label", "score", "averageRank", "rankings", "positions" ], "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "score": { "type": "integer" }, "averageRank": { "type": [ "number", "null" ] }, "rankings": { "type": "integer" }, "positions": { "type": "array", "items": { "type": "integer" } } } } }, "nps": { "type": "object", "description": "nps: promoters 9-10, passives 7-8, detractors 0-6, score -100..100 (1 decimal)", "required": [ "score", "promoters", "passives", "detractors" ], "properties": { "score": { "type": [ "number", "null" ] }, "promoters": { "type": "integer" }, "passives": { "type": "integer" }, "detractors": { "type": "integer" } } } } } } }, "required": [ "meta", "overview", "totalResponses", "questions" ] } }, "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "py_live__", "description": "API key of the organization (dashboard: Settings → API keys)." } } }, "security": [ { "apiKey": [] } ], "tags": [ { "name": "Surveys", "description": "Surveys and polls (scopes surveys:read, surveys:write)" }, { "name": "Responses", "description": "Responses with their answers (scopes responses:read, responses:write)" }, { "name": "Analytics", "description": "Key figures and results (scope analytics:read)" } ] }