{ "openapi": "3.0.3", "info": { "title": "forms", "version": "0.0.1", "description": "📝 Simple surveys and questionnaires, self-hosted", "license": { "name": "AGPL-3.0-or-later" } }, "components": { "securitySchemes": { "basic_auth": { "type": "http", "scheme": "basic" }, "bearer_auth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Access": { "type": "object", "properties": { "permitAllUsers": { "type": "boolean" }, "showToAllUsers": { "type": "boolean" } } }, "Answer": { "type": "object", "required": [ "id", "submissionId", "fileId", "questionId", "text" ], "properties": { "id": { "type": "integer", "format": "int64" }, "submissionId": { "type": "integer", "format": "int64" }, "fileId": { "type": "integer", "format": "int64", "nullable": true }, "questionId": { "type": "integer", "format": "int64" }, "questionName": { "type": "string" }, "text": { "type": "string" } } }, "Capabilities": { "type": "object", "required": [ "forms" ], "properties": { "forms": { "type": "object", "required": [ "version", "apiVersions" ], "properties": { "version": { "type": "string" }, "apiVersions": { "type": "array", "items": { "type": "string" } } } } } }, "Form": { "type": "object", "required": [ "id", "hash", "title", "description", "ownerId", "created", "access", "expires", "fileFormat", "fileId", "isAnonymous", "isMaxSubmissionsReached", "lastUpdated", "submitMultiple", "allowEditSubmissions", "showExpiration", "canSubmit", "permissions", "questions", "state", "lockedBy", "lockedUntil", "maxSubmissions", "shares", "submissionMessage", "confirmationEmailEnabled", "confirmationEmailSubject", "confirmationEmailBody", "confirmationEmailQuestionId", "allowComments" ], "properties": { "id": { "type": "integer", "format": "int64" }, "hash": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "ownerId": { "type": "string" }, "created": { "type": "integer", "format": "int64" }, "access": { "$ref": "#/components/schemas/Access" }, "expires": { "type": "integer", "format": "int64" }, "fileFormat": { "type": "string", "nullable": true }, "fileId": { "type": "integer", "format": "int64", "nullable": true }, "filePath": { "type": "string", "nullable": true }, "isAnonymous": { "type": "boolean" }, "isMaxSubmissionsReached": { "type": "boolean" }, "lastUpdated": { "type": "integer", "format": "int64" }, "submitMultiple": { "type": "boolean" }, "allowEditSubmissions": { "type": "boolean" }, "showExpiration": { "type": "boolean" }, "canSubmit": { "type": "boolean" }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/Permission" } }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/Question" } }, "state": { "type": "integer", "format": "int64", "enum": [ 0, 1, 2 ] }, "lockedBy": { "type": "string", "nullable": true }, "lockedUntil": { "type": "integer", "format": "int64", "nullable": true }, "maxSubmissions": { "type": "integer", "format": "int64", "nullable": true }, "shares": { "type": "array", "items": { "$ref": "#/components/schemas/Share" } }, "submissionCount": { "type": "integer", "format": "int64" }, "submissionMessage": { "type": "string", "nullable": true }, "confirmationEmailEnabled": { "type": "boolean" }, "confirmationEmailSubject": { "type": "string", "nullable": true }, "confirmationEmailBody": { "type": "string", "nullable": true }, "confirmationEmailQuestionId": { "type": "integer", "format": "int64", "nullable": true }, "allowComments": { "type": "boolean" } } }, "OCSMeta": { "type": "object", "required": [ "status", "statuscode" ], "properties": { "status": { "type": "string" }, "statuscode": { "type": "integer" }, "message": { "type": "string" }, "totalitems": { "type": "string" }, "itemsperpage": { "type": "string" } } }, "Option": { "type": "object", "required": [ "id", "questionId", "text", "order" ], "properties": { "id": { "type": "integer", "format": "int64" }, "questionId": { "anyOf": [ { "type": "integer", "format": "int64" }, { "type": "number", "format": "double" } ] }, "text": { "type": "string" }, "order": { "type": "integer", "format": "int64", "nullable": true }, "optionType": { "type": "string", "enum": [ "choice", "row", "column" ] } } }, "Order": { "type": "object", "required": [ "order" ], "properties": { "order": { "type": "integer", "format": "int64" } } }, "PartialForm": { "type": "object", "required": [ "id", "hash", "title", "expires", "permissions", "partial", "state", "lockedBy", "lockedUntil", "maxSubmissions" ], "properties": { "id": { "type": "integer", "format": "int64" }, "hash": { "type": "string" }, "title": { "type": "string" }, "expires": { "type": "integer", "format": "int64" }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/Permission" } }, "partial": { "type": "boolean", "enum": [ true ] }, "state": { "type": "integer", "format": "int64" }, "lockedBy": { "type": "string", "nullable": true }, "lockedUntil": { "type": "integer", "format": "int64", "nullable": true }, "maxSubmissions": { "type": "integer", "format": "int64", "nullable": true } } }, "Permission": { "type": "string", "enum": [ "edit", "results", "results_delete", "submit", "embed" ] }, "Question": { "type": "object", "required": [ "id", "formId", "order", "type", "isRequired", "text", "name", "description", "extraSettings", "options", "accept" ], "properties": { "id": { "type": "integer", "format": "int64" }, "formId": { "type": "integer", "format": "int64" }, "order": { "type": "integer", "format": "int64" }, "type": { "$ref": "#/components/schemas/QuestionType" }, "isRequired": { "type": "boolean" }, "text": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "extraSettings": { "anyOf": [ { "$ref": "#/components/schemas/QuestionExtraSettings" }, { "type": "object", "additionalProperties": true } ] }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/Option" } }, "accept": { "type": "array", "items": { "type": "string" } } } }, "QuestionExtraSettings": { "type": "object", "properties": { "allowOtherAnswer": { "type": "boolean" }, "allowedFileExtensions": { "type": "array", "items": { "type": "string" } }, "allowedFileTypes": { "type": "array", "items": { "type": "string" } }, "dateMax": { "oneOf": [ { "type": "string" }, { "type": "integer", "format": "int64" } ] }, "dateMin": { "oneOf": [ { "type": "string" }, { "type": "integer", "format": "int64" } ] }, "dateRange": { "type": "boolean" }, "maxAllowedFilesCount": { "type": "integer", "format": "int64" }, "maxFileSize": { "type": "integer", "format": "int64" }, "optionsHighest": { "type": "integer", "format": "int64", "enum": [ 2, 3, 4, 5, 6, 7, 8, 9, 10 ] }, "optionsLabelHighest": { "type": "string" }, "optionsLabelLowest": { "type": "string" }, "optionsLimitMax": { "type": "integer", "format": "int64" }, "optionsLimitMin": { "type": "integer", "format": "int64" }, "optionsLowest": { "type": "integer", "format": "int64", "enum": [ 0, 1 ] }, "shuffleOptions": { "type": "boolean" }, "timeMax": { "type": "string" }, "timeMin": { "type": "string" }, "timeRange": { "type": "boolean" }, "validationRegex": { "type": "string" }, "validationType": { "type": "string" }, "questionType": { "type": "string" } } }, "QuestionGridCellType": { "type": "string", "enum": [ "checkbox", "number", "radio" ] }, "QuestionType": { "type": "string", "enum": [ "dropdown", "multiple", "multiple_unique", "date", "time", "short", "long", "file", "datetime", "grid" ] }, "Share": { "type": "object", "required": [ "id", "formId", "shareType", "shareWith", "permissions", "displayName" ], "properties": { "id": { "type": "integer", "format": "int64" }, "formId": { "type": "integer", "format": "int64" }, "shareType": { "type": "integer", "format": "int64" }, "shareWith": { "type": "string" }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/Permission" } }, "displayName": { "type": "string" } } }, "Submission": { "type": "object", "required": [ "id", "formId", "userId", "timestamp", "answers", "userDisplayName" ], "properties": { "id": { "type": "integer", "format": "int64" }, "formId": { "type": "integer", "format": "int64" }, "userId": { "type": "string" }, "timestamp": { "type": "integer", "format": "int64" }, "answers": { "type": "array", "items": { "$ref": "#/components/schemas/Answer" } }, "userDisplayName": { "type": "string" } } }, "Submissions": { "type": "object", "required": [ "submissions", "questions", "filteredSubmissionsCount" ], "properties": { "submissions": { "type": "array", "items": { "$ref": "#/components/schemas/Submission" } }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/Question" } }, "filteredSubmissionsCount": { "type": "integer", "format": "int64" } } }, "UploadedFile": { "type": "object", "required": [ "uploadedFileId", "fileName", "uploadToken" ], "properties": { "uploadedFileId": { "type": "integer", "format": "int64" }, "fileName": { "type": "string" }, "uploadToken": { "type": "string" } } } } }, "paths": { "/ocs/v2.php/apps/forms/api/v3/forms": { "get": { "operationId": "api-get-forms", "summary": "Get all forms available to the user (owned/shared)", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "type", "in": "query", "description": "The type of forms to retrieve. Defaults to `owned`. Possible values: - `owned`: Forms owned by the user. - `shared`: Forms shared with the user.", "schema": { "type": "string", "default": "owned" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Array containing the partial owned or shared forms", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartialForm" } } } } } } } } }, "400": { "description": "wrong form type supplied", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } }, "post": { "operationId": "api-new-form", "summary": "Create a new form and return the form Return a copy of the form if the parameter $fromId is set", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "fromId": { "type": "integer", "format": "int64", "nullable": true, "default": null, "description": "(optional) Id of the form that should be cloned" } } } } } }, "parameters": [ { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "201": { "description": "the created form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "$ref": "#/components/schemas/Form" } } } } } } } }, "403": { "description": "The user is not allowed to create forms", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } } }, "/ocs/v2.php/apps/forms/api/v3/forms/{formId}": { "get": { "operationId": "api-get-form", "summary": "Read all information to edit a Form (form, questions, options, except submissions/answers)", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "formId", "in": "path", "description": "Id of the form", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the requested form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "$ref": "#/components/schemas/Form" } } } } } } } }, "400": { "description": "Could not find form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "User has no permissions to get this form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } }, "patch": { "operationId": "api-update-form", "summary": "Writes the given key-value pairs into Database", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "keyValuePairs" ], "properties": { "keyValuePairs": { "type": "object", "description": "Array of key=>value pairs to update.", "additionalProperties": { "type": "object" } } } } } } }, "parameters": [ { "name": "formId", "in": "path", "description": "FormId of form to update", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the id of the updated form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "oneOf": [ { "type": "integer", "format": "int64" }, { "type": "string" } ] } } } } } } } }, "400": { "description": "Could not find new form owner", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "User is not allowed to modify the form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } }, "delete": { "operationId": "api-delete-form", "summary": "Delete a form", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "formId", "in": "path", "description": "the form id", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the id of the deleted form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "type": "integer", "format": "int64" } } } } } } } }, "403": { "description": "User is not allowed to delete the form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } } }, "/ocs/v2.php/apps/forms/api/v3/forms/{formId}/questions": { "get": { "operationId": "api-get-questions", "summary": "Read all questions (including options)", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "formId", "in": "path", "description": "the form id", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the questions of the given form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Question" } } } } } } } } }, "403": { "description": "User has no permissions to get this form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Could not find form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } }, "post": { "operationId": "api-new-question", "summary": "Add a new question", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/QuestionType", "default": null, "description": "the new question type" }, "subtype": { "$ref": "#/components/schemas/QuestionGridCellType", "default": null, "description": "the new question subtype" }, "text": { "type": "string", "default": "", "description": "the new question title" }, "fromId": { "type": "integer", "format": "int64", "nullable": true, "default": null, "description": "(optional) id of the question that should be cloned" }, "position": { "type": "integer", "format": "int64", "nullable": true, "default": null, "description": "(optional) the position of the new question" } } } } } }, "parameters": [ { "name": "formId", "in": "path", "description": "the form id", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "201": { "description": "the created question", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "$ref": "#/components/schemas/Question" } } } } } } } }, "400": { "description": "Datetime question type no longer supported", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "This form is archived and can not be modified", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Could not find question", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } }, "patch": { "operationId": "api-reorder-questions", "summary": "Updates the Order of all Questions of a Form", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "newOrder" ], "properties": { "newOrder": { "type": "array", "description": "Array of Question-Ids in new order.", "items": { "type": "integer", "format": "int64" } } } } } } }, "parameters": [ { "name": "formId", "in": "path", "description": "Id of the form to reorder", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the question ids of the given form in the new order", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Order" } } } } } } } } }, "400": { "description": "One question has already been marked as deleted", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "User has no permissions to get this form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Could not find question", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } } }, "/ocs/v2.php/apps/forms/api/v3/forms/{formId}/questions/{questionId}": { "get": { "operationId": "api-get-question", "summary": "Read a specific question (including options)", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "formId", "in": "path", "description": "FormId", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "questionId", "in": "path", "description": "QuestionId", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the requested question", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "$ref": "#/components/schemas/Question" } } } } } } } }, "400": { "description": "Question doesn\\'t belong to given Form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "User has no permissions to get this form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Could not find form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } }, "patch": { "operationId": "api-update-question", "summary": "Writes the given key-value pairs into Database Key `order` should only be changed by reorderQuestions() and is not allowed here", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "keyValuePairs" ], "properties": { "keyValuePairs": { "type": "object", "description": "Array of key=>value pairs to update.", "additionalProperties": { "type": "object" } } } } } } }, "parameters": [ { "name": "formId", "in": "path", "description": "the form id", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "questionId", "in": "path", "description": "id of question to update", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the id of the updated question", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "type": "integer", "format": "int64" } } } } } } } }, "400": { "description": "Invalid extraSettings, will not update.", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "User has no permissions to get this form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Could not find question", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } }, "delete": { "operationId": "api-delete-question", "summary": "Delete a question", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "formId", "in": "path", "description": "the form id", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "questionId", "in": "path", "description": "the question id", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the id of the deleted question", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "type": "integer", "format": "int64" } } } } } } } }, "400": { "description": "Question doesn\\'t belong to given Form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "User has no permissions to get this form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Could not find question", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } } }, "/ocs/v2.php/apps/forms/api/v3/forms/{formId}/questions/{questionId}/options": { "post": { "operationId": "api-new-option", "summary": "Add a new option to a question", "description": "Returns a DataResponse containing the added options\nThis endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "optionTexts" ], "properties": { "optionTexts": { "type": "array", "description": "the new option text", "items": { "type": "string" } }, "optionType": { "type": "string", "nullable": true, "default": "choice", "description": "the new option type (e.g. 'row'), defaults to 'choice'" } } } } } }, "parameters": [ { "name": "formId", "in": "path", "description": "id of the form", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "questionId", "in": "path", "description": "id of the question", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "201": { "description": "the created option", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Option" } } } } } } } } }, "400": { "description": "This question is not part ot the given form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "Current user has no permission to edit", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Could not find question", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } }, "patch": { "operationId": "api-reorder-options", "summary": "Reorder options for a given question", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "newOrder" ], "properties": { "newOrder": { "type": "array", "description": "Array of option ids in new order.", "items": { "type": "integer", "format": "int64" } }, "optionType": { "type": "string", "nullable": true, "default": null, "description": "the new option type (e.g. 'row')" } } } } } }, "parameters": [ { "name": "formId", "in": "path", "description": "id of form", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "questionId", "in": "path", "description": "id of question", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the options of the question in the new order", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Order" } } } } } } } } }, "400": { "description": "This option is not part of the given question", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "Current user has no permission to edit", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Could not find question", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } } }, "/ocs/v2.php/apps/forms/api/v3/forms/{formId}/questions/{questionId}/options/{optionId}": { "patch": { "operationId": "api-update-option", "summary": "Writes the given key-value pairs into Database", "description": "Returns the id of the updated option\nThis endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "keyValuePairs" ], "properties": { "keyValuePairs": { "type": "object", "description": "Array of key=>value pairs to update.", "additionalProperties": { "type": "object" } } } } } } }, "parameters": [ { "name": "formId", "in": "path", "description": "id of form", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "questionId", "in": "path", "description": "id of question", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "optionId", "in": "path", "description": "id of option to update", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the id of the updated option", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "type": "integer", "format": "int64" } } } } } } } }, "400": { "description": "The given option id doesn't match the question or form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "Not allowed to update id or questionId", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Could not find option or question", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } }, "delete": { "operationId": "api-delete-option", "summary": "Delete an option", "description": "Returns the id of the deleted option\nThis endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "formId", "in": "path", "description": "id of form", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "questionId", "in": "path", "description": "id of question", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "optionId", "in": "path", "description": "id of option to update", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the id of the deleted option", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "type": "integer", "format": "int64" } } } } } } } }, "400": { "description": "The given option id doesn't match the question or form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "Current user has no permission to edit", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Could not find question or option", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } } }, "/ocs/v2.php/apps/forms/api/v3/forms/{formId}/submissions": { "get": { "operationId": "api-get-submissions", "summary": "Get all the submissions of a given form", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "formId", "in": "path", "description": "of the form", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "query", "in": "query", "description": "(optional) A search query to filter submissions", "schema": { "type": "string", "nullable": true, "default": null } }, { "name": "limit", "in": "query", "description": "(optional) The maximum number of submissions to retrieve. Defaults to `null`", "schema": { "type": "integer", "format": "int64", "nullable": true, "default": null } }, { "name": "offset", "in": "query", "description": "(optional) The offset for pagination. Defaults to `0`", "schema": { "type": "integer", "format": "int64", "default": 0 } }, { "name": "fileFormat", "in": "query", "description": "(optional) The file format that should be used for the download. Defaults to `null` Possible values: - `csv`: Comma-separated value - `ods`: OpenDocument Spreadsheet - `xlsx`: Excel Open XML Spreadsheet", "schema": { "type": "string", "nullable": true, "default": null } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the submissions of the form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "$ref": "#/components/schemas/Submissions" } } } } } }, "text/csv": { "schema": { "type": "string", "format": "binary" } }, "application/vnd.oasis.opendocument.spreadsheet": { "schema": { "type": "string", "format": "binary" } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Could not find form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "The current user has no permission to get the results for this form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } }, "delete": { "operationId": "api-delete-all-submissions", "summary": "Delete all submissions of a specified form", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "formId", "in": "path", "description": "the form id", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the form id of the deleted submission", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "type": "integer", "format": "int64" } } } } } } } }, "404": { "description": "Could not find form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "This form is not owned by the current user and user has no `results_delete` permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } }, "post": { "operationId": "api-new-submission", "summary": "Process a new submission", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ {}, { "basic_auth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "answers" ], "properties": { "answers": { "type": "object", "description": "[question_id => arrayOfString]", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "shareHash": { "type": "string", "default": "", "description": "public share-hash -> Necessary to submit on public link-shares." } } } } } }, "parameters": [ { "name": "formId", "in": "path", "description": "the form id", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "201": { "description": "empty response", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "nullable": true } } } } } } } }, "400": { "description": "At least one submitted answer is not valid", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "This form is not owned by the current user and user has no `results_delete` permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Could not find form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } } }, "/ocs/v2.php/apps/forms/api/v3/forms/{formId}/submissions/{submissionId}": { "get": { "operationId": "api-get-submission", "summary": "Get a specific submission", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "formId", "in": "path", "description": "of the form", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "submissionId", "in": "path", "description": "of the submission", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the submissions of the form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "$ref": "#/components/schemas/Submission" } } } } } } } }, "400": { "description": "Submission doesn't belong to given form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Submission doesn't exist", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "The current user has no permission to get this submission", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } }, "put": { "operationId": "api-update-submission", "summary": "Update an existing submission", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ {}, { "basic_auth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "answers" ], "properties": { "answers": { "type": "object", "description": "[question_id => arrayOfString]", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } } } }, "parameters": [ { "name": "formId", "in": "path", "description": "the form id", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "submissionId", "in": "path", "description": "the submission id", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the id of the updated submission", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "type": "integer", "format": "int64" } } } } } } } }, "400": { "description": "Can only update submission if allowEditSubmissions is set and the answers are valid", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "Can only update your own submission", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } }, "delete": { "operationId": "api-delete-submission", "summary": "Delete a specific submission", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "formId", "in": "path", "description": "the form id", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "submissionId", "in": "path", "description": "the submission id", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the id of the deleted submission", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "type": "integer", "format": "int64" } } } } } } } }, "400": { "description": "Submission doesn't belong to given form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Could not find form or submission", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "This form is not owned by the current user and user has no `results_delete` permission", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } } }, "/ocs/v2.php/apps/forms/api/v3/forms/{formId}/submissions/export": { "post": { "operationId": "api-export-submissions-to-cloud", "summary": "Export Submissions to the Cloud", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ { "basic_auth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string", "description": "The Cloud-Path to export to" }, "fileFormat": { "type": "string", "description": "File format used for export" } } } } } }, "parameters": [ { "name": "formId", "in": "path", "description": "of the form", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the file name used for storing the submissions", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "type": "string" } } } } } } } }, "403": { "description": "The current user has no permission to get the results for this form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Could not find form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } } }, "/ocs/v2.php/apps/forms/api/v3/forms/{formId}/submissions/files/{questionId}": { "post": { "operationId": "api-upload-files", "summary": "Uploads a temporary files to the server during form filling", "description": "This endpoint allows CORS requests", "tags": [ "api" ], "security": [ {}, { "basic_auth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "shareHash": { "type": "string", "default": "", "description": "hash of the form share" } } } } } }, "parameters": [ { "name": "formId", "in": "path", "description": "id of the form", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "questionId", "in": "path", "description": "id of the question", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the file id and name of the uploaded file", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/UploadedFile" } } } } } } } } }, "400": { "description": "File type is not allowed", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "Already submitted", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Could not find question", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } } }, "/ocs/v2.php/apps/forms/api/v3/forms/{formId}/shares": { "post": { "operationId": "share_api-new-share", "summary": "Add a new share", "description": "This endpoint allows CORS requests", "tags": [ "share_api" ], "security": [ { "basic_auth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "shareType" ], "properties": { "shareType": { "type": "integer", "format": "int64", "description": "Nextcloud-ShareType" }, "shareWith": { "type": "string", "default": "", "description": "ID of user/group/... to share with. For Empty shareWith and shareType Link, this will be set as RandomID." }, "permissions": { "type": "array", "default": [], "description": "the permissions granted on the share, defaults to `submit` Possible values: - `submit` user can submit - `results` user can see the results - `results_delete` user can see and delete results", "items": { "type": "string" } } } } } } }, "parameters": [ { "name": "formId", "in": "path", "description": "The form to share", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "201": { "description": "the created share", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "$ref": "#/components/schemas/Share" } } } } } } } }, "400": { "description": "Teams app is disabled", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "This form is not owned by the current user", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Could not find form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } } }, "/ocs/v2.php/apps/forms/api/v3/forms/{formId}/shares/{shareId}": { "patch": { "operationId": "share_api-update-share", "summary": "Update properties of a share", "description": "This endpoint allows CORS requests", "tags": [ "share_api" ], "security": [ { "basic_auth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "keyValuePairs" ], "properties": { "keyValuePairs": { "type": "object", "description": "Array of key=>value pairs to update.", "additionalProperties": { "type": "object" } } } } } } }, "parameters": [ { "name": "formId", "in": "path", "description": "of the form", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "shareId", "in": "path", "description": "of the share to update", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the id of the updated share", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "type": "integer", "format": "int64" } } } } } } } }, "400": { "description": "Invalid share token", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "Not allowed to update unknown properties", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Could not find share", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } }, "delete": { "operationId": "share_api-delete-share", "summary": "Delete a share", "description": "This endpoint allows CORS requests", "tags": [ "share_api" ], "security": [ { "basic_auth": [] } ], "parameters": [ { "name": "formId", "in": "path", "description": "of the form", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "shareId", "in": "path", "description": "of the share to delete", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "the id of the deleted share", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "type": "integer", "format": "int64" } } } } } } } }, "400": { "description": "Share doesn't belong to given Form", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "403": { "description": "This form is not owned by the current user", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "404": { "description": "Could not find share", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } } }, "/ocs/v2.php/apps/forms/api/v3/token": { "get": { "operationId": "share_api-generate-token", "summary": "Get a unique share token", "tags": [ "share_api" ], "security": [ { "bearer_auth": [] }, { "basic_auth": [] } ], "parameters": [ { "name": "OCS-APIRequest", "in": "header", "description": "Required to be true for the API request to pass", "required": true, "schema": { "type": "boolean", "default": true } } ], "responses": { "403": { "description": "Custom public share tokens are not allowed", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } }, "200": { "description": "Token generated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } } } } } } } } }, "401": { "description": "Current user is not logged in", "content": { "application/json": { "schema": { "type": "object", "required": [ "ocs" ], "properties": { "ocs": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/OCSMeta" }, "data": {} } } } } } } } } } } }, "tags": [] }