{ "openapi": "3.1.0", "info": { "title": "KoboToolbox Primary API", "version": "2.0.0 (api_v2)", "description": "This page documents all KoboToolbox API endpoints, except for those implementing the OpenRosa protocol, which are [documented separately](/api/openrosa/docs/).\n\nThe endpoints are grouped by area of intended use. Each category contains related endpoints, with detailed documentation on usage and configuration. Use this as a reference to quickly find the right endpoint for managing projects, forms, data, permissions, integrations, logs, and organizational resources.\n\n**General note**: All projects (whether deployed or draft), as well as all library content (questions, blocks, templates, and collections) in the user-facing application are represented in the API as \"assets\"." }, "paths": { "/api/v2/access-logs/": { "get": { "operationId": "api_v2_access_logs_list", "description": "## List all access logs for all users\n\n⚠️ _Only available to superusers_\n\nSubmissions will be grouped together by user by hour\n\n**Filterable fields:**\n\n- date_created\n- user_uid\n- user__username\n- metadata__source\n- metadata__auth_type\n- metadata__ip_address\n\n**Some examples:**\n\n1. All logs from a specific IP address\n `api/v2/access-logs/?q=metadata__ip_address:\"127.0.0.1\"`\n\n2. All logs created after Jan 1, 2025\n `api/v2/access-logs/?q=date_created__gte:\"2025-01-01\"`\n\n*Notes: Do not forget to wrap search terms in double-quotes if they contain spaces\n(e.g. date and time \"2022-11-15 20:34\")*\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "in": "query", "name": "q", "schema": { "type": "string" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "Server logs (superusers)" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSuperUserAccessLogResponseList" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" } } } }, "/api/v2/access-logs/export/": { "get": { "operationId": "api_v2_access_logs_export_list", "description": "## List all access logs export tasks for all users\n\n⚠️ _Only available to superusers_\n", "tags": [ "Server logs (superusers)" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExportListResponse" } } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" } } }, "post": { "operationId": "api_v2_access_logs_export_create", "description": "## Create an export task for all users\n\n⚠️ _Only available to superusers_\n", "tags": [ "Server logs (superusers)" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportCreateResponse" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" } } } }, "/api/v2/access-logs/me/": { "get": { "operationId": "api_v2_access_logs_me_list", "description": "## List all access logs for the authenticated user\n\nSubmissions will be grouped together by hour\n\nResults from this endpoint can be filtered by a boolean query specified in the `q` parameter.\n\n**Filterable fields:**\n\n* date_created\n* metadata__source\n* metadata__auth_type\n* metadata__ip_address\n\n**Some examples:**\n\n* All logs from a specific IP address\n `api/v2/access-logs/?q=metadata__ip_address:\"127.0.0.1\"`\n* All logs created after Jan, 1 2025\n `api/v2/access-logs/?q=date_created__date__gte:\"2025-01-01\"`\n\n*Notes: Do not forget to wrap search terms in double-quotes if they contain spaces\n(e.g. date and time \"2022-11-15 20:34\")*\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "in": "query", "name": "q", "schema": { "type": "string" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "Logging" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAccessLogResponseList" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" } } } }, "/api/v2/access-logs/me/export/": { "get": { "operationId": "api_v2_access_logs_me_export_list", "description": "## List all access logs export tasks for the authenticated user\n", "tags": [ "Logging" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExportListResponse" } } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" } } }, "post": { "operationId": "api_v2_access_logs_me_export_create", "description": "## Create an export task for the authenticated user\n", "tags": [ "Logging" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportCreateResponse" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" } } } }, "/api/v2/asset_snapshots/": { "get": { "operationId": "api_v2_asset_snapshots_list", "description": "## List all snapshots for every asset of a user\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "Form content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAssetSnapshotResponseList" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" } } }, "post": { "operationId": "api_v2_asset_snapshots_create", "description": "## Create an asset snapshot\n\nWhen creating an asset snapshot, you must provide either:\n\n- the asset (as a URI), or\n- the source (as a JSON object representing the asset)\n\n…but not both.\n", "tags": [ "Form content" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetSnapshotCreateRequest" }, "examples": { "UsingAsset": { "value": { "asset": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/", "details": { "status": "string", "warnings": [ { "code": "string", "message": "string" } ] } }, "summary": "Using asset" }, "UsingSource": { "value": { "source": { "schema": "string", "survey": [ { "name": "string", "type": "string" } ], "settings": { "form_title": "string" }, "translated": [ "string" ], "translation": [ "string" ] }, "details": { "status": "string", "warnings": [ { "code": "string", "message": "string" } ] } }, "summary": "Using source" } } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetSnapshotResponse" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/asset_snapshots/{uid_asset_snapshot}/": { "get": { "operationId": "api_v2_asset_snapshots_retrieve", "description": "## Retrieve an asset snapshot\n\nNote: If the `Content-Type` of the request is set to `application/xml`, the response will\nreturn the XML version of the form, rather than the JSON representation of the asset\nsnapshot.\n", "parameters": [ { "in": "query", "name": "format", "schema": { "type": "string", "enum": [ "json", "xml" ] } }, { "in": "path", "name": "uid_asset_snapshot", "schema": { "type": "string" }, "description": "UID of the asset snapshot", "required": true } ], "tags": [ "Form content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetSnapshotResponse" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/AssetSnapshotResponse" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "delete": { "operationId": "api_v2_asset_snapshots_destroy", "description": "## Delete an asset snapshot\n", "parameters": [ { "in": "path", "name": "uid_asset_snapshot", "schema": { "type": "string" }, "description": "UID of the asset snapshot", "required": true } ], "tags": [ "Form content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "204": { "description": "No response body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/asset_snapshots/{uid_asset_snapshot}/preview/": { "get": { "operationId": "api_v2_asset_snapshots_preview_retrieve", "description": "## Asset snapshot preview\n\nReturns a `302 Found` redirect to the Enketo preview page associated with the asset.\n", "parameters": [ { "in": "path", "name": "uid_asset_snapshot", "schema": { "type": "string" }, "description": "UID of the asset snapshot", "required": true } ], "tags": [ "Form content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "302": { "description": "No response body" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/asset_snapshots/{uid_asset_snapshot}/xform/": { "get": { "operationId": "api_v2_asset_snapshots_xform_retrieve", "description": "## This route will render the XForm into syntax-highlighted HTML.\n\nIt is useful for debugging pyxform transformations\n", "parameters": [ { "in": "path", "name": "uid_asset_snapshot", "schema": { "type": "string" }, "description": "UID of the asset snapshot", "required": true } ], "tags": [ "Form content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/xml": { "schema": { "$ref": "#/components/schemas/OpenRosaXFormResponse" } } }, "description": null }, "404": { "description": "No response body" } } } }, "/api/v2/asset_snapshots/{uid_asset_snapshot}/xml_with_disclaimer/": { "get": { "operationId": "api_v2_asset_snapshots_xml_with_disclaimer_retrieve", "description": "## Implement part of the OpenRosa Form List API\n\nThis endpoint is used by Enketo to fetch and return the full XML form.\nIt behaves like the standard retrieve endpoint but includes an additional ``\nnode containing the disclaimer, if one exists.\n", "parameters": [ { "in": "path", "name": "uid_asset_snapshot", "schema": { "type": "string" }, "description": "UID of the asset snapshot", "required": true } ], "tags": [ "Form content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/xml": { "schema": { "$ref": "#/components/schemas/OpenRosaXFormResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/asset_subscriptions/": { "get": { "operationId": "api_v2_asset_subscriptions_list", "description": "## List all asset subscriptions of a user\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "Library collections" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, {} ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAssetSubscriptionResponseList" } } }, "description": null } } }, "post": { "operationId": "api_v2_asset_subscriptions_create", "description": "## Create an asset subscription\n\nCreate a subscription to a public collection for the user.\n", "tags": [ "Library collections" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetSubscriptionRequest" } } }, "required": true }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, {} ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetSubscriptionResponse" } } }, "description": null }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/asset_subscriptions/{uid_asset_subscription}/": { "get": { "operationId": "api_v2_asset_subscriptions_retrieve", "description": "## Retrieve an asset subscription\n", "parameters": [ { "in": "path", "name": "uid_asset_subscription", "schema": { "type": "string" }, "required": true } ], "tags": [ "Library collections" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, {} ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetSubscriptionResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "delete": { "operationId": "api_v2_asset_subscriptions_destroy", "description": "## Delete a subscription to an asset\n\nUnsubscribe from a public asset.\n", "parameters": [ { "in": "path", "name": "uid_asset_subscription", "schema": { "type": "string" }, "required": true } ], "tags": [ "Library collections" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, {} ], "responses": { "204": { "description": "No response body" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/asset_usage/": { "get": { "operationId": "api_v2_asset_usage_list", "description": "## Get user's asset usage\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAssetUsageResponseList" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" } } } }, "/api/v2/assets/": { "get": { "operationId": "api_v2_assets_list", "description": "## Get user's assets\n\n\nSearch can be made with `q` parameter.\nSearch filters can be returned with results by passing `metadata=on` to querystring.\n\n\nResults can be sorted with `ordering` parameter, e.g.:\n\n```shell\ncurl -X GET https://kf.kobotoolbox.org/api/v2/assets/?ordering=-name\n```\n\n\nAllowed fields are:\n\n- `asset_type`\n- `date_modified`\n- `date_deployed`\n- `date_modified__date`\n- `date_deployed__date`\n- `name`\n- `settings__sector`\n- `settings__sector__value`\n- `settings__description`\n- `owner__username`\n- `owner__extra_details__data__name`\n- `owner__extra_details__data__organization`\n- `owner__email`\n- `_deployment_status`\n- `subscribers_count`\n\n\nNote: Collections can be displayed first with parameter `collections_first`, e.g.:\n\n```shell\ncurl -X GET https://kf.kobotoolbox.org/api/v2/assets/?collections_first=true&ordering=-name\n```\n", "parameters": [ { "in": "query", "name": "current_user_permissions_only", "schema": { "type": "boolean" }, "description": "When `true`, only return the requesting user's own permission assignments. When `false` (default), return all visible assignments." }, { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "in": "query", "name": "ordering", "schema": { "type": "string" }, "description": "Which field to use when ordering the results." }, { "in": "query", "name": "q", "schema": { "type": "string" }, "description": "Filter the results with search query" }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "Manage projects and library content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAssetList" } } }, "description": null } } }, "post": { "operationId": "api_v2_assets_create", "description": "## Create or clone an asset\n\nWhen cloning an asset, you must provide:\n\n- the name (as a string),\n- the `clone_from` (the uid representing the asset),\n- the asset_type\n\nWhere `asset_type` must be one of these values:\n\n* block (can be cloned to `block`, `question`, `survey`, `template`)\n* question (can be cloned to `question`, `survey`, `template`)\n* survey (can be cloned to `block`, `question`, `survey`, `template`)\n* template (can be cloned to `survey`, `template`)\n\nSettings are cloned only when type of assets are `survey` or `template`.\nIn that case, `share-metadata` is not preserved.\n\nWhen creating a new `block` or `question` asset, settings are not saved either.\n", "tags": [ "Manage projects and library content" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetCreateRequest" }, "examples": { "CreatingAnAsset": { "value": { "name": "string", "settings": { "description": "string", "sector": "string", "country": "string", "share-metadata": true }, "asset_type": "string" }, "summary": "Creating an asset" }, "CloningAnAsset": { "value": { "name": "string", "clone_from": "string", "asset_type": "string" }, "summary": "Cloning an asset" } } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/": { "get": { "operationId": "api_v2_assets_retrieve", "description": "## Get a user's current asset\n", "parameters": [ { "in": "query", "name": "format", "schema": { "type": "string", "enum": [ "json", "ssjson", "xls", "xml" ] } }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "required": true } ], "tags": [ "Manage projects and library content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Asset" } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "$ref": "#/components/schemas/Asset" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "patch": { "operationId": "api_v2_assets_partial_update", "description": "## Update or connect a user's asset\n\nUpdates a project or connect project's data from this project to other projects\n\nWhen `Data sharing`:\n\n`fields`: Optional. List of questions whose responses will be shared. If\nmissing or empty, all responses will be shared. Questions must be\nidentified by full group path separated by slashes, e.g.\n`group/subgroup/question_name`.\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "required": true } ], "tags": [ "Manage projects and library content" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedAssetPatchRequest" }, "examples": { "UpdatingAnAsset": { "value": { "content": "string", "name": "string" }, "summary": "Updating an asset" }, "DataSharingOfTheProject": { "value": { "data_sharing": { "enabled": true, "fields": [ "string" ] } }, "summary": "Data sharing of the project" } } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } }, "delete": { "operationId": "api_v2_assets_destroy", "description": "## Delete a user's asset\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "required": true } ], "tags": [ "Manage projects and library content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "204": { "description": "No response body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/advanced-features/": { "get": { "operationId": "api_v2_assets_advanced_features_list", "description": "## List all advanced features on an asset\n\nLists all advanced features on all questions in an asset. Examples show one type at a time, but the response may contain multiple advanced features items.\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AdvancedFeatureResponse" } }, "examples": { "NLPAdvancedFeatures": { "value": [ { "action": "", "question_xpath": "q1", "params": [ { "language": "es" }, { "language": "en" } ], "uid": "qa123456789AbCdEfGhIjklm" } ], "summary": "NLP Advanced Features", "description": "`` can be any of:\n\n* `manual_transcription`\n* `manual_translation`\n* `automatic_google_transcription`\n* `automatic_google_translation`\n" }, "ManualQualitativeAnalysis-SimpleTypes_": { "value": [ { "action": "manual_qual", "question_xpath": "q1", "params": [ { "type": "", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Qualitative analysis result" } } ], "uid": "qa123456789AbCdEfGhIjklm" } ], "summary": "Manual Qualitative Analysis - Simple Types ", "description": "`` may be any of:\n\n* `qualText`\n* `qualInteger`\n* `qualNote`\n* `qualTags`\n" }, "ManualQualitativeAnalysis-SingleChoiceQuestion": { "value": [ { "action": "manual_qual", "question_xpath": "q1", "params": [ { "type": "qualSelectOne", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Urgency Level" }, "choices": [ { "uuid": "qqqqqqqq-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "High" } }, { "uuid": "hhhhhhhh-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Medium" } }, { "uuid": "gggggggg-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Low" } } ] } ], "uid": "qa123456789AbCdEfGhIjklm" } ], "summary": "Manual Qualitative Analysis - Single Choice Question" }, "ManualQualitativeAnalysis-MultipleChoiceQuestion(withDeletedChoice)": { "value": [ { "action": "manual_qual", "question_xpath": "q1", "params": [ { "type": "qualSelectMultiple", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Tags" }, "choices": [ { "uuid": "xxxxxxxx-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Shelter" }, "options": { "deleted": true } }, { "uuid": "zzzzzzzz-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Food" } }, { "uuid": "yyyyyyyy-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Medical" } } ] } ], "uid": "qa123456789AbCdEfGhIjklm" } ], "summary": "Manual Qualitative Analysis - Multiple Choice Question (with deleted choice)" }, "ManualQualitativeAnalysis-DeletedQuestion": { "value": [ { "action": "manual_qual", "question_xpath": "q1", "params": [ { "type": "", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Qualitative analysis result" } } ], "options": { "deleted": true }, "uid": "qa123456789AbCdEfGhIjklm" } ], "summary": "Manual Qualitative Analysis - Deleted Question" }, "ManualQualitativeAnalysis-QuestionWithHints": { "value": [ { "action": "manual_qual", "question_xpath": "q1", "params": [ { "type": "qualSelectMultiple", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Tags" }, "hint": { "labels": { "_default": "Select the most appropriate" } }, "choices": [ { "uuid": "zzzzzzzz-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Food" }, "hint": { "labels": { "_default": "Include water" } } }, { "uuid": "yyyyyyyy-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Medical" }, "hint": { "labels": { "_default": "Include dental work" } } } ] } ], "uid": "qa123456789AbCdEfGhIjklm" } ], "summary": "Manual Qualitative Analysis - Question With Hints" }, "AutomaticQualitativeAnalysis-AnyQuestion": { "value": [ { "action": "automatic_bedrock_qual", "question_xpath": "q1", "params": [ { "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff" } ], "uid": "qa123456789AbCdEfGhIjklm" } ], "summary": "Automatic Qualitative Analysis - Any question" } } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "post": { "operationId": "api_v2_assets_advanced_features_create", "description": "## Add an advanced action to an asset\n\nEnables a new type of advanced action on a question in the asset.\n* `action`, `params`, and `question_xpath` are required\n* `params` must match the expected param_schema of the `action`\n\nAccepted `action`s include:\n* `manual_transcription`\n* `automatic_google_transcription`\n* `manual_translation`\n* `automatic_google_translation`\n* `manual_qual`\n\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvancedFeaturePostRequest" }, "examples": { "NLPAdvancedFeatures": { "value": { "action": "", "question_xpath": "q1", "params": [ { "language": "es" }, { "language": "fr" } ] }, "summary": "NLP Advanced Features", "description": "`` can be any of:\n\n* `manual_transcription`\n* `manual_translation`\n* `automatic_google_transcription`\n* `automatic_google_translation`\n" }, "ManualQualitativeAnalysis-SimpleTypes": { "value": { "action": "manual_qual", "question_xpath": "q1", "params": [ { "type": "", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Qualitative analysis result" } } ] }, "summary": "Manual Qualitative Analysis - Simple Types", "description": "`` may be any of:\n\n* `qualText`\n* `qualInteger`\n* `qualNote`\n* `qualTags`\n" }, "ManualQualitativeAnalysis-SingleChoiceQuestion": { "value": { "action": "manual_qual", "question_xpath": "q1", "params": [ { "type": "qualSelectOne", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Urgency Level" }, "choices": [ { "uuid": "qqqqqqqq-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "High" } }, { "uuid": "hhhhhhhh-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Medium" } }, { "uuid": "gggggggg-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Low" } } ] } ] }, "summary": "Manual Qualitative Analysis - Single Choice Question" }, "ManualQualitativeAnalysis-MultipleChoiceQuestion": { "value": { "action": "manual_qual", "question_xpath": "q1", "params": [ { "type": "qualSelectMultiple", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Tags" }, "choices": [ { "uuid": "xxxxxxxx-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Shelter" } }, { "uuid": "zzzzzzzz-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Food" } }, { "uuid": "yyyyyyyy-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Medical" } } ] } ] }, "summary": "Manual Qualitative Analysis - Multiple Choice Question" }, "ManualQualitativeAnalysis-Hints": { "value": { "action": "manual_qual", "question_xpath": "q1", "params": [ { "type": "qualSelectOne", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Favorite shade of blue?" }, "hint": { "labels": { "_default": "Select closest shade" } }, "choices": [ { "uuid": "qqqqqqqq-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Midnight" }, "hint": { "labels": { "_default": "Darkest blue" } } }, { "uuid": "hhhhhhhh-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Royal" }, "hint": { "labels": { "_default": "True blue" } } }, { "uuid": "gggggggg-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Cornflower" }, "hint": { "labels": { "_default": "Lightest blue" } } } ] } ] }, "summary": "Manual Qualitative Analysis - Hints", "description": "Question hints are allowed for all types of questions. Choice hints are allowed for all questions with choices." }, "AutomaticQualitativeAnalysis-AnyQuestion": { "value": { "action": "automatic_bedrock_qual", "question_xpath": "q1", "params": [ { "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff" } ] }, "summary": "Automatic Qualitative Analysis - Any Question", "description": "`uuid`s should match those present in the `manual_qual` action for the same survey question." } } } }, "required": true }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvancedFeatureCreateResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/advanced-features/{uid_advanced_feature}/": { "get": { "operationId": "api_v2_assets_advanced_features_retrieve", "description": "## Retrieve advanced feature configuration for a question on an asset\n\nGets the params for one advanced action for one question in an asset\n", "parameters": [ { "in": "path", "name": "uid_advanced_feature", "schema": { "type": "string" }, "description": "UID of the advanced feature", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvancedFeatureResponse" }, "examples": { "NLPAdvancedFeatures": { "value": { "action": "", "question_xpath": "q1", "params": [ { "language": "es" }, { "language": "en" } ], "uid": "qa123456789AbCdEfGhIjklm" }, "summary": "NLP Advanced Features", "description": "`` can be any of:\n\n* `manual_transcription`\n* `manual_translation`\n* `automatic_google_transcription`\n* `automatic_google_translation`\n" }, "ManualQualitativeAnalysis-SimpleTypes_": { "value": { "action": "manual_qual", "question_xpath": "q1", "params": [ { "type": "", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Qualitative analysis result" } } ], "uid": "qa123456789AbCdEfGhIjklm" }, "summary": "Manual Qualitative Analysis - Simple Types ", "description": "`` may be any of:\n\n* `qualText`\n* `qualInteger`\n* `qualNote`\n* `qualTags`\n" }, "ManualQualitativeAnalysis-SingleChoiceQuestion": { "value": { "action": "manual_qual", "question_xpath": "q1", "params": [ { "type": "qualSelectOne", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Urgency Level" }, "choices": [ { "uuid": "qqqqqqqq-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "High" } }, { "uuid": "hhhhhhhh-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Medium" } }, { "uuid": "gggggggg-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Low" } } ] } ], "uid": "qa123456789AbCdEfGhIjklm" }, "summary": "Manual Qualitative Analysis - Single Choice Question" }, "ManualQualitativeAnalysis-MultipleChoiceQuestion(withDeletedChoice)": { "value": { "action": "manual_qual", "question_xpath": "q1", "params": [ { "type": "qualSelectMultiple", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Tags" }, "choices": [ { "uuid": "xxxxxxxx-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Shelter" }, "options": { "deleted": true } }, { "uuid": "zzzzzzzz-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Food" } }, { "uuid": "yyyyyyyy-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Medical" } } ] } ], "uid": "qa123456789AbCdEfGhIjklm" }, "summary": "Manual Qualitative Analysis - Multiple Choice Question (with deleted choice)" }, "ManualQualitativeAnalysis-DeletedQuestion": { "value": { "action": "manual_qual", "question_xpath": "q1", "params": [ { "type": "", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Qualitative analysis result" } } ], "options": { "deleted": true }, "uid": "qa123456789AbCdEfGhIjklm" }, "summary": "Manual Qualitative Analysis - Deleted Question" }, "ManualQualitativeAnalysis-QuestionWithHints": { "value": { "action": "manual_qual", "question_xpath": "q1", "params": [ { "type": "qualSelectMultiple", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Tags" }, "hint": { "labels": { "_default": "Select the most appropriate" } }, "choices": [ { "uuid": "zzzzzzzz-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Food" }, "hint": { "labels": { "_default": "Include water" } } }, { "uuid": "yyyyyyyy-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Medical" }, "hint": { "labels": { "_default": "Include dental work" } } } ] } ], "uid": "qa123456789AbCdEfGhIjklm" }, "summary": "Manual Qualitative Analysis - Question With Hints" }, "AutomaticQualitativeAnalysis-AnyQuestion": { "value": { "action": "automatic_bedrock_qual", "question_xpath": "q1", "params": [ { "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff" } ], "uid": "qa123456789AbCdEfGhIjklm" }, "summary": "Automatic Qualitative Analysis - Any question" } } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "patch": { "operationId": "api_v2_assets_advanced_features_partial_update", "description": "## Update an advanced action on an asset\n\nUpdate the params of an advanced action on a question in the asset.\n`params` are always additive. That means that if you PATCH a feature with a new param array, the new ones\nwill be added to the existing ones. You cannot delete a param via the API.\n\nIn the case of NLP actions, this means you can only add languages, not delete.\nIn the case of QA analysis questions, you should send the full set questions and choices in the desired order. Any existing\nchoices or questions in the existing params not present in the new ones will be marked as deleted, but not actually removed from the data.\nDeleted questions and choices will be placed at the end of the relevant list.\n\n* `params` is required\n* `params` must match the expected param_schema of the action being updated\n\n\n", "parameters": [ { "in": "path", "name": "uid_advanced_feature", "schema": { "type": "string" }, "description": "UID of the advanced feature", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedAdvancedFeaturePatchRequest" }, "examples": { "NLPAdvancedFeatures": { "value": { "params": [ { "language": "es" }, { "language": "fr" } ] }, "summary": "NLP Advanced Features", "description": "This may be used to update any of the NLP actions:\n\n* `manual_transcription`\n* `manual_translation`\n* `automatic_google_transcription`\n* `automatic_google_translation`\n" }, "ManualQualitativeAnalysis-SimpleTypes": { "value": { "params": [ { "type": "", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Qualitative analysis result" } } ] }, "summary": "Manual Qualitative Analysis - Simple Types", "description": "`` may be any of:\n\n* `qualText`\n* `qualInteger`\n* `qualNote`\n* `qualTags`\n" }, "ManualQualitativeAnalysis-SingleChoiceQuestion": { "value": { "params": [ { "type": "qualSelectOne", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Urgency Level" }, "choices": [ { "uuid": "qqqqqqqq-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "High" } }, { "uuid": "hhhhhhhh-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Medium" } }, { "uuid": "gggggggg-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Low" } } ] } ] }, "summary": "Manual Qualitative Analysis - Single Choice Question" }, "ManualQualitativeAnalysis-MultipleChoiceQuestion": { "value": { "params": [ { "type": "qualSelectMultiple", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Tags" }, "choices": [ { "uuid": "xxxxxxxx-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Shelter" } }, { "uuid": "zzzzzzzz-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Food" } }, { "uuid": "yyyyyyyy-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Medical" } } ] } ] }, "summary": "Manual Qualitative Analysis - Multiple Choice Question" }, "AutomaticQualitativeAnalysis-AllTypes": { "value": { "params": [ { "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff" }, { "uuid": "dddddddd-eeee-ffff-gggg-hhhhhhhhhhhhh" } ] }, "summary": "Automatic Qualitative Analysis - All Types", "description": "`uuid`s should match those present in the `manual_qual` action for the same survey question." } } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvancedFeatureResponse" }, "examples": { "NLPAdvancedFeatures": { "value": { "action": "", "question_xpath": "q1", "params": [ { "language": "es" }, { "language": "en" } ], "uid": "qa123456789AbCdEfGhIjklm" }, "summary": "NLP Advanced Features", "description": "`` can be any of:\n\n* `manual_transcription`\n* `manual_translation`\n* `automatic_google_transcription`\n* `automatic_google_translation`\n" }, "ManualQualitativeAnalysis-SimpleTypes_": { "value": { "action": "manual_qual", "question_xpath": "q1", "params": [ { "type": "", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Qualitative analysis result" } } ], "uid": "qa123456789AbCdEfGhIjklm" }, "summary": "Manual Qualitative Analysis - Simple Types ", "description": "`` may be any of:\n\n* `qualText`\n* `qualInteger`\n* `qualNote`\n* `qualTags`\n" }, "ManualQualitativeAnalysis-SingleChoiceQuestion": { "value": { "action": "manual_qual", "question_xpath": "q1", "params": [ { "type": "qualSelectOne", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Urgency Level" }, "choices": [ { "uuid": "qqqqqqqq-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "High" } }, { "uuid": "hhhhhhhh-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Medium" } }, { "uuid": "gggggggg-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Low" } } ] } ], "uid": "qa123456789AbCdEfGhIjklm" }, "summary": "Manual Qualitative Analysis - Single Choice Question" }, "ManualQualitativeAnalysis-MultipleChoiceQuestion(withDeletedChoice)": { "value": { "action": "manual_qual", "question_xpath": "q1", "params": [ { "type": "qualSelectMultiple", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Tags" }, "choices": [ { "uuid": "xxxxxxxx-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Shelter" }, "options": { "deleted": true } }, { "uuid": "zzzzzzzz-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Food" } }, { "uuid": "yyyyyyyy-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Medical" } } ] } ], "uid": "qa123456789AbCdEfGhIjklm" }, "summary": "Manual Qualitative Analysis - Multiple Choice Question (with deleted choice)" }, "ManualQualitativeAnalysis-DeletedQuestion": { "value": { "action": "manual_qual", "question_xpath": "q1", "params": [ { "type": "", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Qualitative analysis result" } } ], "options": { "deleted": true }, "uid": "qa123456789AbCdEfGhIjklm" }, "summary": "Manual Qualitative Analysis - Deleted Question" }, "ManualQualitativeAnalysis-QuestionWithHints": { "value": { "action": "manual_qual", "question_xpath": "q1", "params": [ { "type": "qualSelectMultiple", "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Tags" }, "hint": { "labels": { "_default": "Select the most appropriate" } }, "choices": [ { "uuid": "zzzzzzzz-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Food" }, "hint": { "labels": { "_default": "Include water" } } }, { "uuid": "yyyyyyyy-bbbb-cccc-dddd-eeeeffffffff", "labels": { "_default": "Medical" }, "hint": { "labels": { "_default": "Include dental work" } } } ] } ], "uid": "qa123456789AbCdEfGhIjklm" }, "summary": "Manual Qualitative Analysis - Question With Hints" }, "AutomaticQualitativeAnalysis-AnyQuestion": { "value": { "action": "automatic_bedrock_qual", "question_xpath": "q1", "params": [ { "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff" } ], "uid": "qa123456789AbCdEfGhIjklm" }, "summary": "Automatic Qualitative Analysis - Any question" } } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/advanced-features/bulk-actions/": { "get": { "operationId": "api_v2_assets_advanced_features_bulk_actions_list", "description": "## List bulk processing jobs on an asset\n\nReturns paginated bulk processing jobs associated with the specified asset. Each\njob is organized around one action, one question, and many submissions.\n\nUse this endpoint to monitor recently-created bulk transcription and translation\njobs. Each result includes the parent job status, per-submission statuses, the\noriginal deterministic params, the user who created the job, cancellation\nmetadata, and integer `progress` from `0` to `100`.\n\nOptional query params:\n\n* `status`: Filter by parent job status. Accepts a comma-separated list,\n for example `status=pending,in_progress`.\n* `submission_uuid`: Return only jobs that include this submission.\n* `question_xpath`: Return only jobs for this question xpath.\n\nJob statuses:\n\n* `pending`: the job exists but has not started.\n* `in_progress`: one or more child submissions are still active.\n* `complete`: every child submission has reached a terminal state.\n* `cancelled`: the job was cancelled.\n\nChild submission statuses:\n\n* `pending`\n* `in_progress`\n* `complete`\n* `failed`\n* `cancelled`\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "in": "query", "name": "question_xpath", "schema": { "type": "string" }, "description": "Filter jobs to this question xpath." }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } }, { "in": "query", "name": "status", "schema": { "type": "string" }, "description": "Filter by parent job status. Accepts comma-separated values, e.g. \"pending,in_progress\"." }, { "in": "query", "name": "submission_uuid", "schema": { "type": "string" }, "description": "Filter jobs to those containing this submission UUID." }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionListResponse" }, "examples": { "BulkTranscriptionJobListResponse": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "uid": "ba123456789AbCdEfGhIjklm", "status": "in_progress", "action_id": "automatic_google_transcription", "question_xpath": "q1_audio", "submission_uuids": [ "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "0ca3624a-6f22-451e-8d0a-c40978fd6fe2", "5d4958d6-b2e8-4d4b-a51f-63f91b459e26" ], "submission_statuses": [ { "uuid": "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "status": "complete", "error": null }, { "uuid": "0ca3624a-6f22-451e-8d0a-c40978fd6fe2", "status": "in_progress", "error": null }, { "uuid": "5d4958d6-b2e8-4d4b-a51f-63f91b459e26", "status": "failed", "error": "Google quota exceeded" } ], "params": { "language": "en", "locale": "en-US" }, "progress": 66, "created_by": { "username": "someuser" }, "date_created": "2026-05-05T09:00:00Z", "date_modified": "2026-05-05T09:02:00Z", "cancelled_by": null } ] }, "summary": "Bulk transcription job list response" }, "BulkTranslationJobListResponse": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "uid": "ba123456789AbCdEfGhIjklm", "status": "in_progress", "action_id": "automatic_google_translation", "question_xpath": "q1_transcript", "submission_uuids": [ "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "0ca3624a-6f22-451e-8d0a-c40978fd6fe2", "5d4958d6-b2e8-4d4b-a51f-63f91b459e26" ], "submission_statuses": [ { "uuid": "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "status": "complete", "error": null }, { "uuid": "0ca3624a-6f22-451e-8d0a-c40978fd6fe2", "status": "in_progress", "error": null }, { "uuid": "5d4958d6-b2e8-4d4b-a51f-63f91b459e26", "status": "failed", "error": "Google quota exceeded" } ], "params": { "language": "fr" }, "progress": 66, "created_by": { "username": "someuser" }, "date_created": "2026-05-05T09:00:00Z", "date_modified": "2026-05-05T09:02:00Z", "cancelled_by": null } ] }, "summary": "Bulk translation job list response" } } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "post": { "operationId": "api_v2_assets_advanced_features_bulk_actions_create", "description": "## Create a bulk processing job\n\nCreates and starts a bulk processing job for one question across multiple\nsubmissions.\n\nSupported actions:\n\n* `automatic_google_transcription`\n* `automatic_google_translation`\n\nThe request must include the target `question_xpath`, the submission root UUIDs\nto process, and deterministic `params`. `params.language` is required. For\ntranscription, `params.locale` may also be supplied when a more specific Google\nSpeech locale is needed.\n\nCreation is atomic. If any selected submission is unknown, already has matching\nresults, or already has an active matching bulk action, no job or child items are\ncreated.\n\nThe response is the created job. Its initial status is `in_progress` because\ncreation immediately starts background processing.\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionCreateRequest" }, "examples": { "BulkTranscriptionJob": { "value": { "action_id": "automatic_google_transcription", "question_xpath": "q1_audio", "submission_uuids": [ "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "0ca3624a-6f22-451e-8d0a-c40978fd6fe2" ], "params": { "language": "en", "locale": "en-US" } }, "summary": "Bulk transcription job", "description": "Starts Google transcription for the selected audio question across the listed submissions. `locale` is optional." }, "BulkTranslationJob": { "value": { "action_id": "automatic_google_translation", "question_xpath": "q1_transcript", "submission_uuids": [ "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "0ca3624a-6f22-451e-8d0a-c40978fd6fe2" ], "params": { "language": "fr" } }, "summary": "Bulk translation job", "description": "Starts Google translation for the selected question across the listed submissions. `language` is the target language." } } } }, "required": true }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionCreateResponse" }, "examples": { "BulkTranscriptionJobResponse": { "value": { "uid": "ba123456789AbCdEfGhIjklm", "status": "in_progress", "action_id": "automatic_google_transcription", "question_xpath": "q1_audio", "submission_uuids": [ "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "0ca3624a-6f22-451e-8d0a-c40978fd6fe2", "5d4958d6-b2e8-4d4b-a51f-63f91b459e26" ], "submission_statuses": [ { "uuid": "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "status": "complete", "error": null }, { "uuid": "0ca3624a-6f22-451e-8d0a-c40978fd6fe2", "status": "in_progress", "error": null }, { "uuid": "5d4958d6-b2e8-4d4b-a51f-63f91b459e26", "status": "failed", "error": "Google quota exceeded" } ], "params": { "language": "en", "locale": "en-US" }, "progress": 66, "created_by": { "username": "someuser" }, "date_created": "2026-05-05T09:00:00Z", "date_modified": "2026-05-05T09:02:00Z", "cancelled_by": null, "skipped_uuids": [] }, "summary": "Bulk transcription job response", "description": "Bulk transcription responses include the action params used to start the job. `locale` appears when it was supplied." }, "BulkTranslationJobResponse": { "value": { "uid": "ba123456789AbCdEfGhIjklm", "status": "in_progress", "action_id": "automatic_google_translation", "question_xpath": "q1_transcript", "submission_uuids": [ "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "0ca3624a-6f22-451e-8d0a-c40978fd6fe2", "5d4958d6-b2e8-4d4b-a51f-63f91b459e26" ], "submission_statuses": [ { "uuid": "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "status": "complete", "error": null }, { "uuid": "0ca3624a-6f22-451e-8d0a-c40978fd6fe2", "status": "in_progress", "error": null }, { "uuid": "5d4958d6-b2e8-4d4b-a51f-63f91b459e26", "status": "failed", "error": "Google quota exceeded" } ], "params": { "language": "fr" }, "progress": 66, "created_by": { "username": "someuser" }, "date_created": "2026-05-05T09:00:00Z", "date_modified": "2026-05-05T09:02:00Z", "cancelled_by": null, "skipped_uuids": [] }, "summary": "Bulk translation job response" }, "BulkActionResponse(withSkippedSubmissions)": { "value": { "uid": "ba123456789AbCdEfGhIjklm", "status": "in_progress", "action_id": "automatic_google_transcription", "question_xpath": "q1_audio", "submission_uuids": [ "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "0ca3624a-6f22-451e-8d0a-c40978fd6fe2", "5d4958d6-b2e8-4d4b-a51f-63f91b459e26" ], "submission_statuses": [ { "uuid": "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "status": "complete", "error": null }, { "uuid": "0ca3624a-6f22-451e-8d0a-c40978fd6fe2", "status": "in_progress", "error": null }, { "uuid": "5d4958d6-b2e8-4d4b-a51f-63f91b459e26", "status": "failed", "error": "Google quota exceeded" } ], "params": { "language": "en", "locale": "en-US" }, "progress": 66, "created_by": { "username": "someuser" }, "date_created": "2026-05-05T09:00:00Z", "date_modified": "2026-05-05T09:02:00Z", "cancelled_by": null, "skipped_uuids": [ "7a1b2c3d-e4f5-6789-abcd-ef0123456789" ] }, "summary": "Bulk action response (with skipped submissions)", "description": "When some submitted UUIDs were already processed or currently being processed, they are excluded from the new bulk action and listed in `skipped_uuids`. The job proceeds for the remaining eligible submissions." } } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/advanced-features/bulk-actions/{action_uid}/": { "get": { "operationId": "api_v2_assets_advanced_features_bulk_actions_retrieve", "description": "## Retrieve a bulk processing job\n\nReturns detailed information about a single bulk processing job, including its\ncurrent status, per-submission status, processing params, creator, cancellation\nmetadata, timestamps, and integer `progress` from `0` to `100`.\n\nThe response shape is identical to the item returned by the bulk job creation\nendpoint and to each item in the paginated list response.\n", "parameters": [ { "in": "path", "name": "action_uid", "schema": { "type": "string" }, "description": "UID of the bulk action job", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionResponse" }, "examples": { "BulkTranscriptionJobResponse": { "value": { "uid": "ba123456789AbCdEfGhIjklm", "status": "in_progress", "action_id": "automatic_google_transcription", "question_xpath": "q1_audio", "submission_uuids": [ "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "0ca3624a-6f22-451e-8d0a-c40978fd6fe2", "5d4958d6-b2e8-4d4b-a51f-63f91b459e26" ], "submission_statuses": [ { "uuid": "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "status": "complete", "error": null }, { "uuid": "0ca3624a-6f22-451e-8d0a-c40978fd6fe2", "status": "in_progress", "error": null }, { "uuid": "5d4958d6-b2e8-4d4b-a51f-63f91b459e26", "status": "failed", "error": "Google quota exceeded" } ], "params": { "language": "en", "locale": "en-US" }, "progress": 66, "created_by": { "username": "someuser" }, "date_created": "2026-05-05T09:00:00Z", "date_modified": "2026-05-05T09:02:00Z", "cancelled_by": null }, "summary": "Bulk transcription job response" }, "BulkTranslationJobResponse": { "value": { "uid": "ba123456789AbCdEfGhIjklm", "status": "in_progress", "action_id": "automatic_google_translation", "question_xpath": "q1_transcript", "submission_uuids": [ "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "0ca3624a-6f22-451e-8d0a-c40978fd6fe2", "5d4958d6-b2e8-4d4b-a51f-63f91b459e26" ], "submission_statuses": [ { "uuid": "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "status": "complete", "error": null }, { "uuid": "0ca3624a-6f22-451e-8d0a-c40978fd6fe2", "status": "in_progress", "error": null }, { "uuid": "5d4958d6-b2e8-4d4b-a51f-63f91b459e26", "status": "failed", "error": "Google quota exceeded" } ], "params": { "language": "fr" }, "progress": 66, "created_by": { "username": "someuser" }, "date_created": "2026-05-05T09:00:00Z", "date_modified": "2026-05-05T09:02:00Z", "cancelled_by": null }, "summary": "Bulk translation job response" } } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "patch": { "operationId": "api_v2_assets_advanced_features_bulk_actions_partial_update", "description": "## Update a bulk processing job\n\nCancels a single bulk processing job for an asset. This endpoint currently only\nsupports cancellation.\n\nRequest body:\n\n```json\n{\n \"status\": \"cancelled\"\n}\n```\n\nCancellation is idempotent. Cancelling an already-cancelled job returns the\ncurrent cancelled job. Completed jobs cannot be cancelled.\n\nWhen a job is cancelled, pending and in-progress child items are marked\n`cancelled`; terminal child items are not modified. The response is the updated\njob, including `cancelled_by`.\n", "parameters": [ { "in": "path", "name": "action_uid", "schema": { "type": "string" }, "description": "UID of the bulk action job", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedBulkActionPatchRequest" }, "examples": { "BulkActionCancelRequest": { "value": { "status": "cancelled" }, "summary": "Bulk action cancel request" } } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkActionResponse" }, "examples": { "CancelledBulkTranscriptionJobResponse": { "value": { "uid": "ba123456789AbCdEfGhIjklm", "status": "cancelled", "action_id": "automatic_google_transcription", "question_xpath": "q1_audio", "submission_uuids": [ "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "0ca3624a-6f22-451e-8d0a-c40978fd6fe2", "5d4958d6-b2e8-4d4b-a51f-63f91b459e26" ], "submission_statuses": [ { "uuid": "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "status": "complete", "error": null }, { "uuid": "0ca3624a-6f22-451e-8d0a-c40978fd6fe2", "status": "cancelled", "error": null }, { "uuid": "5d4958d6-b2e8-4d4b-a51f-63f91b459e26", "status": "failed", "error": "Google quota exceeded" } ], "params": { "language": "en", "locale": "en-US" }, "progress": 100, "created_by": { "username": "someuser" }, "date_created": "2026-05-05T09:00:00Z", "date_modified": "2026-05-05T09:02:00Z", "cancelled_by": { "username": "someuser" } }, "summary": "Cancelled bulk transcription job response", "description": "The cancelled response shows active child items moved to `cancelled`; terminal child items remain unchanged." }, "CancelledBulkTranslationJobResponse": { "value": { "uid": "ba123456789AbCdEfGhIjklm", "status": "cancelled", "action_id": "automatic_google_translation", "question_xpath": "q1_transcript", "submission_uuids": [ "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "0ca3624a-6f22-451e-8d0a-c40978fd6fe2", "5d4958d6-b2e8-4d4b-a51f-63f91b459e26" ], "submission_statuses": [ { "uuid": "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "status": "complete", "error": null }, { "uuid": "0ca3624a-6f22-451e-8d0a-c40978fd6fe2", "status": "cancelled", "error": null }, { "uuid": "5d4958d6-b2e8-4d4b-a51f-63f91b459e26", "status": "failed", "error": "Google quota exceeded" } ], "params": { "language": "fr" }, "progress": 100, "created_by": { "username": "someuser" }, "date_created": "2026-05-05T09:00:00Z", "date_modified": "2026-05-05T09:02:00Z", "cancelled_by": { "username": "someuser" } }, "summary": "Cancelled bulk translation job response", "description": "The cancelled response includes the user who cancelled the job in `cancelled_by`." } } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/attachments/{id}/": { "delete": { "operationId": "api_v2_assets_attachments_destroy", "description": "## Delete a specific attachment of an Asset\n\n* `id` can only be the uid of attachment to be deleted\n", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "ID of the attachment", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "204": { "description": "No response body" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/attachments/audio-duration/": { "post": { "operationId": "api_v2_assets_attachments_audio_duration_create", "description": "## Get total audio duration for a list of attachments\n\n```curl\n curl -X POST https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/attachments/audio-duration/\n```\n\n> **Payload**\n>\n> {\n> \"attachment_uids\": [\n> \"attXXXXXXXXXXXXXXXXX\",\n> \"attYYYYYYYYYYYYYYYYY\"\n> ]\n> }\n\n* Where: `attachment_uids` (required) is a list of attachment UIDs whose audio duration to retrieve. Maximum 200 UIDs per request.\n\n\n> **Response**\n>\n> {\n> \"attachments\": [\n> { \"uid\": \"attXXXXXXXXXXXXXXXXX\", \"seconds\": 42 },\n> { \"uid\": \"attYYYYYYYYYYYYYYYYY\", \"seconds\": null }\n> ],\n> \"total\": 42\n> }\n\n* `attachments` - one entry per recognised, accessible UID in the order submitted.\n Unrecognised or inaccessible UIDs are silently omitted.\n* `seconds` - integer duration, or `null` when `ffprobe` could not determine the duration (corrupt file, unsupported format, etc.).\n* `total` - sum of all non-null `seconds` values.\n\n\n### Batching and timeouts\n\n`ffprobe` takes approximately 0.5 s per file. With a 120 s nginx timeout, sending more\nthan ~200 files per request risks a **504 Gateway Timeout**.\n\n* Submit files in small batches from the front-end.\n* Retry on 504 - already-processed attachments will be served from the db, so\n subsequent attempts complete faster.\n* Requests exceeding 200 UIDs are rejected immediately with **400 Bad Request**.\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetAttachmentAudioDurationRequest" } } }, "required": true }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetAttachmentAudioDurationResponse" } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/attachments/bulk/": { "delete": { "operationId": "api_v2_assets_attachments_bulk_destroy", "description": "## Delete all attachments from a list of submissions\n\n```curl\n curl -X DELETE https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/attachments/bulk/\n```\n\n> **Payload**\n>\n> {\n> \"submission_root_uuids\": [\n> \"3ed2e8de-b493-4367-a78d-3463687239dc\",\n> \"ef18fe33-c71d-4638-84d6-dafcbd69c327\"\n> ]\n> }\n\n* Where: \"submission_root_uuids\" (required) is a list of submission root uuids on the asset\nto delete\n\n\n> **Response**\n>\n> {\n> \"message\": \"{number_of_attachment} attachments deleted\"\n> }\n\n* Where: \"number_of_attachment\" is the number of items that was deleted\n\n\n### !! Due to current DRF-Spectacular limitations with AOS 3.1, DELETE operations do not display request or response bodies in this documentation (as payloads are not typically recommended for DELETE). This means direct testing is unavailable. However, example payloads and responses are provided for reference, and HTTP codes/error messages are accurate. !!\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "202": { "description": "No response body" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/content/": { "get": { "operationId": "api_v2_assets_content_retrieve", "description": "## Return the content of a user's asset.\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "required": true } ], "tags": [ "Form content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/counts/": { "get": { "operationId": "api_v2_assets_counts_list", "description": "## Count the daily amount of submissions\n\nReturns up to the last 31 days of daily counts and total counts of submissions to a survey.\n\n\nUse the `days` query to get the daily counts from the last x amount of days.\nDefault amount is 30 days\n\n\n```shell\ncurl -X GET https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/counts/?days=7\n```\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Manage projects and library content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAssetCountResponseList" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/data/": { "get": { "operationId": "api_v2_assets_data_list", "description": "## List of submissions for a specific asset\n\nBy default, JSON format is used, but XML and GeoJSON are also available:\n\n```shell\ncurl -X GET https://kf.kobotoolbox.org/api/v2/assets/{uid}/data/\n```\n\n### Pagination\nTwo parameters can be used to control pagination.\n\n* `start`: Index (zero-based) from which the results start\n* `limit`: Number of results per page Maximum results per page cannot exceed **1000**, unless changed by server configuration\n\n```shell\ncurl -X GET https://kf.kobotoolbox.org/api/v2/assets/{uid}/data/?start=0&limit=10\n```\n\n### Query submitted data\nProvides a list of submitted data for a specific form. Use `query`\nparameter to apply form data specific, see\nhttp://docs.mongodb.org/manual/reference/operator/query/.\n\nFor more details see\nAPI Parameters.\n\n```shell\ncurl -X GET https://kf.kobotoolbox.org/api/v2/assets/{uid}/data/?query={\"__version__\": \"vWvkKzNE8xCtfApJvabfjG\"}\ncurl https://kf.kobotoolbox.org/api/v2/assets/{uid}/data/?query={\"_submission_time\": {\"$gt\": \"2019-09-01T01:02:03\"}}\n```\n\n### About the GeoJSON format\nRequesting the `geojson` format returns a `FeatureCollection` where each\nsubmission is a `Feature`. If your form has multiple geographic questions,\nuse the `geo_question_name` query parameter to determine which question's\nresponses populate the `geometry` for each `Feature`; otherwise, the first\ngeographic question is used. All question/response pairs are included in\nthe `properties` of each `Feature`, but _repeating groups are omitted_.\n\nQuestion types are mapped to GeoJSON geometry types as follows:\n\n* `geopoint` to `Point`;\n* `geotrace` to `LineString`;\n* `geoshape` to `Polygon`.\n\n\n\n### ⚠️ Note: DRF-Spectacular Limitation\n\nDue to limitations in **DRF-Spectacular**, the `ACCEPT` headers do not sync properly with the request. As a result, all responses will default to `application/json`, regardless of the specified format.\n\nThis means that while alternative formats (like XML) are technically supported and will work via command-line tools (e.g., `curl`), **they will not work** when trying out the endpoint directly from the documentation page.\n\nWe’ve still included the header to show supported formats, but keep in mind:\n**Only `application/json` will be used in the docs UI.**\n", "parameters": [ { "in": "query", "name": "fields", "schema": { "type": "string" }, "description": "Include only given list of fields in results" }, { "in": "query", "name": "format", "schema": { "type": "string", "enum": [ "geojson", "json", "xml" ] } }, { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "ID of the data (when applicable)", "required": true }, { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "in": "query", "name": "query", "schema": { "type": "string" }, "description": "Filter the results with search query" }, { "in": "query", "name": "sort", "schema": { "type": "string" }, "description": "Sort the results by a field, e.g. {\"_id\":-1}" }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedDataResponseList" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/PaginatedDataResponseXMLList" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/data/{id}/": { "get": { "operationId": "api_v2_assets_data_retrieve", "description": "## Get a specific submission\n\n`{id}` can be:\n\n- The primary key of the submission\n- Its `_uuid` 1\n- Its `rootUuid` (without \"uuid:\" prefix)\n\n1 Please note that using the `_uuid` may match **several** submissions, only\nthe first match will be returned.\n\n\nIt is also possible to specify the format.\n\n```shell\ncurl -X GET https://kf.kobotoolbox.org/api/v2/assets/{uid_asset}/data/{id}.xml\ncurl -X GET https://kf.kobotoolbox.org/api/v2/assets/{uid_asset}/data/{id}.json\n```\n\nor\n\n```shell\ncurl -X GET https://kf.kobotoolbox.org/api/v2/assets/{uid_asset}/data/{id}/?format=xml\ncurl -X GET https://kf.kobotoolbox.org/api/v2/assets/{uid_asset}/data/{id}/?format=json\n```\n\n### ⚠️ Note: DRF-Spectacular Limitation\n\nDue to limitations in **DRF-Spectacular**, the `ACCEPT` headers do not sync properly with the request. As a result, all responses will default to `application/json`, regardless of the specified format.\n\nThis means that while alternative formats (like XML) are technically supported and will work via command-line tools (e.g., `curl`), **they will not work** when trying out the endpoint directly from the documentation page.\n\nWe’ve still included the header to show supported formats, but keep in mind:\n**Only `application/json` will be used in the docs UI.**\n", "parameters": [ { "in": "query", "name": "format", "schema": { "type": "string", "enum": [ "geojson", "json", "xml" ] } }, { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "Integer ID (PK) or rootUuid", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse" } }, "text/xml": { "schema": { "$ref": "#/components/schemas/DataResponseXML" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "delete": { "operationId": "api_v2_assets_data_destroy", "description": "## Deletes current submission\n", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "Integer ID (PK) or rootUuid", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "204": { "description": "No response body" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/data/{id}/duplicate/": { "post": { "operationId": "api_v2_assets_data_duplicate_create", "description": "## Duplicate submission\n\nDuplicates the data of a submission\n\n`{id}` can be:\n\n- The primary key of the submission\n- Its `_uuid` 1\n- Its `rootUuid` (without \"uuid:\" prefix)\n\n1 Please note that using the `_uuid` may match **several** submissions, only\nthe first match will be returned.\n", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "Integer ID (PK) or rootUuid", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataBulkDelete" } } }, "required": true }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/data/{id}/edit/": { "get": { "operationId": "api_v2_assets_data_edit_retrieve", "description": "## Get submission url of enketo in edit mode\n\n`{id}` can be:\n\n- The primary key of the submission\n- Its `_uuid` 1\n- Its `rootUuid` (without \"uuid:\" prefix)\n\n1 Please note that using the `_uuid` may match **several** submissions, only\nthe first match will be returned.\n\nNote: Some variation of this url exists:\n\n`/api/v2/assets/{uid_asset}/data/{id}/edit/`: deprecated, use the next one.\n\n`/api/v2/assets/{uid_asset}/data/{id}/enketo/edit/`: return the url of the enketo submission (as seen in the response example).\n\n`/api/v2/assets/{uid_asset}/data/{id}/enketo/redirect/edit/`: redirect to the enketo url submission with a 302 HTTP code.\n", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "Integer ID (PK) or rootUuid", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnketoEditResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/data/{id}/enketo/edit/": { "get": { "operationId": "api_v2_assets_data_enketo_edit_retrieve", "description": "## Get submission url of enketo in edit mode\n\n`{id}` can be:\n\n- The primary key of the submission\n- Its `_uuid` 1\n- Its `rootUuid` (without \"uuid:\" prefix)\n\n1 Please note that using the `_uuid` may match **several** submissions, only\nthe first match will be returned.\n\nNote: Some variation of this url exists:\n\n`/api/v2/assets/{uid_asset}/data/{id}/edit/`: deprecated, use the next one.\n\n`/api/v2/assets/{uid_asset}/data/{id}/enketo/edit/`: return the url of the enketo submission (as seen in the response example).\n\n`/api/v2/assets/{uid_asset}/data/{id}/enketo/redirect/edit/`: redirect to the enketo url submission with a 302 HTTP code.\n", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "Integer ID (PK) or rootUuid", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnketoEditResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/data/{id}/enketo/redirect/edit/": { "get": { "operationId": "api_v2_assets_data_enketo_redirect_edit_retrieve", "description": "## Get submission url of enketo in edit mode\n\n`{id}` can be:\n\n- The primary key of the submission\n- Its `_uuid` 1\n- Its `rootUuid` (without \"uuid:\" prefix)\n\n1 Please note that using the `_uuid` may match **several** submissions, only\nthe first match will be returned.\n\nNote: Some variation of this url exists:\n\n`/api/v2/assets/{uid_asset}/data/{id}/edit/`: deprecated, use the next one.\n\n`/api/v2/assets/{uid_asset}/data/{id}/enketo/edit/`: return the url of the enketo submission (as seen in the response example).\n\n`/api/v2/assets/{uid_asset}/data/{id}/enketo/redirect/edit/`: redirect to the enketo url submission with a 302 HTTP code.\n", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "Integer ID (PK) or rootUuid", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnketoEditResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/data/{id}/enketo/redirect/view/": { "get": { "operationId": "api_v2_assets_data_enketo_redirect_view_retrieve", "description": "## Get submission url of enketo in preview mode\n\n`{id}` can be:\n\n- The primary key of the submission\n- Its `_uuid` 1\n- Its `rootUuid` (without \"uuid:\" prefix)\n\n1 Please note that using the `_uuid` may match **several** submissions, only\nthe first match will be returned.\n\nNote: Some variation of this url exists:\n\n`/api/v2/assets/{uid_asset}/data/{id}/enketo/view/`: return the url of the enketo submission (as seen in the response example).\n\n`/api/v2/assets/{uid_asset}/data/{id}/enketo/redirect/view/`: redirect to the enketo url submission with a 302 code.\n", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "Integer ID (PK) or rootUuid", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnketoViewResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/data/{id}/enketo/view/": { "get": { "operationId": "api_v2_assets_data_enketo_view_retrieve", "description": "## Get submission url of enketo in preview mode\n\n`{id}` can be:\n\n- The primary key of the submission\n- Its `_uuid` 1\n- Its `rootUuid` (without \"uuid:\" prefix)\n\n1 Please note that using the `_uuid` may match **several** submissions, only\nthe first match will be returned.\n\nNote: Some variation of this url exists:\n\n`/api/v2/assets/{uid_asset}/data/{id}/enketo/view/`: return the url of the enketo submission (as seen in the response example).\n\n`/api/v2/assets/{uid_asset}/data/{id}/enketo/redirect/view/`: redirect to the enketo url submission with a 302 code.\n", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "Integer ID (PK) or rootUuid", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnketoViewResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/data/{id}/validation_status/": { "get": { "operationId": "api_v2_assets_data_validation_status_retrieve", "description": "## Get validation statuses\nRetrieves the validation status of a submission.\n", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "Integer ID (PK) or rootUuid", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataValidationStatusUpdateResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "patch": { "operationId": "api_v2_assets_data_validation_status_partial_update", "description": "## Update the validation of a submission\n\nThe validation status of the submission can be updated. The `validation_status.uid` should be a `string`, and it must be one of the following values:\n\n- `validation_status_approved`\n- `validation_status_not_approved`\n- `validation_status_on_hold`\n", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "Integer ID (PK) or rootUuid", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedDataValidationStatusUpdatePayload" } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataValidationStatusUpdateResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "delete": { "operationId": "api_v2_assets_data_validation_status_destroy", "description": "## Delete validation status\n", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "Integer ID (PK) or rootUuid", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "204": { "description": "No response body" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/data/{root_uuid}/supplement/": { "get": { "operationId": "api_v2_assets_data_supplement_retrieve", "description": "## Retrieve submission supplementary data\n\nThis endpoint allows you to retrieve supplementary data attached to a submission.\n\nThe supplementary data may include:\n\n* NLP actions\n * Manual transcription\n * Manual translation\n * Automatic Google transcription\n * Automatic Google translation\n* Qualitative analysis - manual or automatic with Bedrock\n * Text\n * Number\n * Single Choice\n * Multiple Choice\n* Qualitative analysis (manual only)\n * Tags\n\n⚠️ The response examples in this documentation show each action in isolation for\nreadability.\n\nIn practice, multiple actions can be combined for the same question, and a single\nsubmission may contain multiple questions.\n", "parameters": [ { "in": "path", "name": "root_uuid", "schema": { "type": "string" }, "description": "Root UUID of the submission", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSupplementResponse" }, "examples": { "ManualTranscription": { "value": { "_version": "20250820", "question_name_xpath": { "manual_transcription": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_dateAccepted": "2025-01-01T12:00:00Z", "_uuid": "11111111-1111-1111-1111-111111111111", "_data": { "language": "fr", "value": "Bonjour" } } ] } } }, "summary": "Manual Transcription" }, "ManualTranscription(with\"locale\")": { "value": { "_version": "20250820", "question_name_xpath": { "manual_transcription": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_dateAccepted": "2025-01-01T12:00:00Z", "_uuid": "11111111-1111-1111-1111-111111111111", "_data": { "language": "fr", "locale": "fr-CA", "value": "Bonjour" } } ] } } }, "summary": "Manual Transcription (with \"locale\")" }, "ManualTranslation": { "value": { "_version": "20250820", "question_name_xpath": { "manual_translation": { "en": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_dateAccepted": "2025-01-01T12:00:00Z", "_uuid": "22222222-2222-2222-2222-222222222222", "_data": { "language": "en", "value": "Hello" }, "_dependency": { "_actionId": "manual_transcription", "_uuid": "11111111-1111-1111-1111-111111111111" } } ] }, "es": { "_dateCreated": "2025-01-01T12:01:00Z", "_dateModified": "2025-01-01T12:01:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:01:00Z", "_dateAccepted": "2025-01-01T12:01:00Z", "_uuid": "33333333-3333-3333-3333-333333333333", "_data": { "language": "es", "value": "Hola" }, "_dependency": { "_actionId": "manual_transcription", "_uuid": "11111111-1111-1111-1111-111111111111" } } ] } } } }, "summary": "Manual Translation" }, "AutomatedGoogleTranscription": { "value": { "_version": "20250820", "question_name_xpath": { "automated_google_transcription": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:01:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:01:00Z", "_uuid": "44444444-4444-4444-4444-444444444444", "_data": { "language": "en", "status": "complete", "value": "Hello world" }, "_dateAccepted": "2025-01-01T12:01:00Z" }, { "_dateCreated": "2025-01-01T12:00:00Z", "_uuid": "44444444-4444-4444-4444-444444444444", "_data": { "language": "en", "status": "in_progress" } } ] } } }, "summary": "Automated Google Transcription" }, "AutomatedGoogleTranslation": { "value": { "_version": "20250820", "question_name_xpath": { "automated_google_translation": { "fr": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:03:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:03:00Z", "_dateAccepted": "2025-01-01T12:03:00Z", "_uuid": "88888888-8888-8888-8888-888888888888", "_data": { "language": "fr", "status": "complete", "value": "Bonjour le monde" }, "_dependency": { "_actionId": "automatic_google_transcription", "_uuid": "44444444-4444-4444-4444-444444444444" } }, { "_dateCreated": "2025-01-01T12:02:00Z", "_uuid": "77777777-7777-7777-7777-777777777777", "_data": { "language": "fr", "status": "in_progress" }, "_dependency": { "_actionId": "automatic_google_transcription", "_uuid": "44444444-4444-4444-4444-444444444444" } }, { "_dateCreated": "2025-01-01T12:01:00Z", "_uuid": "66666666-6666-6666-6666-666666666666", "_data": { "language": "fr", "value": null, "status": "deleted" }, "_dependency": { "_actionId": "automatic_google_transcription", "_uuid": "44444444-4444-4444-4444-444444444444" } }, { "_dateCreated": "2025-01-01T12:00:00Z", "_uuid": "55555555-5555-5555-5555-555555555555", "_data": { "language": "fr", "status": "complete", "value": "Allo la foule" }, "_dependency": { "_actionId": "automatic_google_transcription", "_uuid": "44444444-4444-4444-4444-444444444444" } } ] } } } }, "summary": "Automated Google Translation" }, "QualitativeAnalysis–IntegerQuestion": { "value": { "_version": "20250820", "question_name_xpath": { "": { "66666666-6666-6666-6666-666666666666": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_data": { "uuid": "66666666-6666-6666-6666-666666666666", "value": 42, "status": "complete" }, "_uuid": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", "verified": false } ] } } } }, "summary": "Qualitative Analysis – Integer Question", "description": "`` can be either `manual_qual` or `automatic_bedrock_qual`. \n\n`status` will only be present for automatic_actions." }, "QualitativeAnalysis–TextQuestion": { "value": { "_version": "20250820", "question_name_xpath": { "": { "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_data": { "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "value": "This is a qualitative text response.", "status": "complete" }, "_uuid": "12121212-3434-5656-7878-909090909090", "verified": false } ] } } } }, "summary": "Qualitative Analysis – Text Question", "description": "`` can be either `manual_qual` or `automatic_bedrock_qual`. \n\n`status` will only be present for automatic_actions." }, "QualitativeAnalysis–SingleChoiceQuestion": { "value": { "_version": "20250820", "question_name_xpath": { "": { "77777777-7777-7777-7777-777777777777": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_data": { "uuid": "77777777-7777-7777-7777-777777777777", "value": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", "status": "complete" }, "_uuid": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", "verified": false } ] } } } }, "summary": "Qualitative Analysis – Single Choice Question", "description": "`` can be either `manual_qual` or `automatic_bedrock_qual`. \n\n`status` will only be present for automatic_actions." }, "QualitativeAnalysis–MultipleChoiceQuestion": { "value": { "_version": "20250820", "question_name_xpath": { "": { "88888888-8888-8888-8888-888888888888": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_data": { "uuid": "88888888-8888-8888-8888-888888888888", "value": [ "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb" ], "status": "complete" }, "_uuid": "99999999-9999-9999-9999-999999999999", "verified": false } ] } } } }, "summary": "Qualitative Analysis – Multiple Choice Question", "description": "`` can be either `manual_qual` or `automatic_bedrock_qual`. \n\n`status` will only be present for automatic_actions." }, "ManualQualitativeAnalysis–TagsQuestion": { "value": { "_version": "20250820", "question_name_xpath": { "manual_qual": { "bbbbbbbb-cccc-dddd-eeee-ffffffffffff": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_data": { "uuid": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff", "value": [ "urgent", "review", "priority" ] }, "_uuid": "23232323-4545-6767-8989-010101010101", "verified": false } ] } } } }, "summary": "Manual Qualitative Analysis – Tags Question" }, "QualitativeAnalysis–VerifiedResponse": { "value": { "_version": "20250820", "question_name_xpath": { "": { "bbbbbbbb-cccc-dddd-eeee-ffffffffffff": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_dateVerified": "2025-01-01T12:00:00Z", "_data": { "uuid": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff", "status": "complete", "value": 5 }, "_uuid": "23232323-4545-6767-8989-010101010101", "verified": true } ] } } } }, "summary": "Qualitative Analysis – Verified Response", "description": "`` can be either `manual_qual` or `automatic_bedrock_qual`. " }, "AutomaticQualitativeAnalysis–FailedResponse": { "value": { "_version": "20250820", "question_name_xpath": { "automatic_bedrock_qual": { "bbbbbbbb-cccc-dddd-eeee-ffffffffffff": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_data": { "uuid": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff", "status": "failed", "error": "Cannot parse response from LLM" }, "_uuid": "23232323-4545-6767-8989-010101010101", "verified": false } ] } } } }, "summary": "Automatic Qualitative Analysis – Failed response" } } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } }, "patch": { "operationId": "api_v2_assets_data_supplement_partial_update", "description": "## Update submission supplementary data\n\nThis endpoint allows you to add, update, or delete supplementary data for a submission.\n\nIt supports the same action types as the GET endpoint:\n\n* NLP actions (manual and automatic transcription / translation)\n* Qualitative analysis (manual and automatic)\n\nThe PATCH payload follows the same per-question structure as the GET response.\n\nTo delete a submission supplement, you need to PATCH the submission supplement\nwith the appropriate null or empty value.\n\n⚠️ In this documentation, request and response examples present each action in\nisolation for clarity. In practice, multiple actions may be combined within the same\npayload or response, including for the same question, and a single submission may\ncontain multiple questions.\n", "parameters": [ { "in": "path", "name": "root_uuid", "schema": { "type": "string" }, "description": "Root UUID of the submission", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedDataSupplementPayload" }, "examples": { "ManualTranscription": { "value": { "_version": "20250820", "question_name_xpath": { "manual_transcription": { "language": "fr", "value": "Bonjour" } } }, "summary": "Manual Transcription" }, "ManualTranscription(with\"locale\")": { "value": { "_version": "20250820", "question_name_xpath": { "manual_transcription": { "language": "fr", "locale": "fr-CA", "value": "Bonjour" } } }, "summary": "Manual Transcription (with \"locale\")", "description": "The `locale` field is optional." }, "ManualTranslation": { "value": { "_version": "20250820", "question_name_xpath": { "manual_translation": { "language": "en", "value": "Hello" } } }, "summary": "Manual Translation" }, "AutomicGoogleTranscription": { "value": { "_version": "20250820", "question_name_xpath": { "automatic_google_transcription": { "language": "fr" } } }, "summary": "Automic Google Transcription" }, "AutomicGoogleTranslation": { "value": { "_version": "20250820", "question_name_xpath": { "automatic_google_translation": { "language": "en" } } }, "summary": "Automic Google Translation" }, "DeleteNLPAction": { "value": { "_version": "20250820", "question_name_xpath": { "": { "language": "", "value": null } } }, "summary": "Delete NLP action", "description": "`` can be any of:
* `manual_transcription`
* `manual_translation`
* `automatic_google_transcription`
* `automatic_google_translation`
`` is the language code, e.g. `en`." }, "AcceptAutomaticNLPAction": { "value": { "_version": "20250820", "question_name_xpath": { "": { "language": "", "accepted": true } } }, "summary": "Accept automatic NLP action", "description": "`` can be any of `automatic_google_transcription` or `automatic_google_translation`.
`` is the language code, e.g. `en`.
`accepted` is a boolean. It can `true` or `false`." }, "ManualQualitativeAnalysis–IntegerQuestion": { "value": { "_version": "20250820", "question_name_xpath": { "manual_qual": { "uuid": "11111111-1111-1111-1111-111111111111", "value": 42 } } }, "summary": "Manual Qualitative Analysis – Integer Question", "description": "Set `value` to `null` to delete." }, "ManualQualitativeAnalysis–TextQuestion": { "value": { "_version": "20250820", "question_name_xpath": { "manual_qual": { "uuid": "22222222-2222-2222-2222-222222222222", "value": "example-text" } } }, "summary": "Manual Qualitative Analysis – Text Question" }, "ManualQualitativeAnalysis–SingleChoiceQuestion": { "value": { "_version": "20250820", "question_name_xpath": { "manual_qual": { "uuid": "33333333-3333-3333-3333-333333333333", "value": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa" } } }, "summary": "Manual Qualitative Analysis – Single Choice Question", "description": "Set `value` to the empty string `\"\"` to delete." }, "ManualQualitativeAnalysis–MultipleChoiceQuestion": { "value": { "_version": "20250820", "question_name_xpath": { "manual_qual": { "uuid": "44444444-4444-4444-4444-444444444444", "value": [ "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb" ] } } }, "summary": "Manual Qualitative Analysis – Multiple Choice Question", "description": "Set `value` to the empty string `\"\"` to delete." }, "ManualQualitativeAnalysis–TagsQuestion": { "value": { "_version": "20250820", "question_name_xpath": { "manual_qual": { "uuid": "44444444-4444-4444-4444-444444444444", "value": [ "tag1", "tag2" ] } } }, "summary": "Manual Qualitative Analysis – Tags Question", "description": "Set `value` an empty array `[]` to delete." }, "AutomaticBedrockQualitativeAnalysis–AnyQuestion": { "value": { "_version": "20250820", "question_name_xpath": { "automatic_bedrock_qual": { "uuid": "44444444-4444-4444-4444-444444444444" } } }, "summary": "Automatic Bedrock Qualitative Analysis – Any Question" }, "VerifyQualitativeAnalysisResponse–AnyQuestion": { "value": { "_version": "20250820", "question_name_xpath": { "": { "uuid": "44444444-4444-4444-4444-4444444444444", "verified": true } } }, "summary": "Verify Qualitative Analysis Response – Any Question", "description": "`` may be either `manual_qual` or `automatic_bedrock_qual`\n\nSet `verified` to `False` to un-verify" } } } }, "required": true }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSupplementResponse" }, "examples": { "ManualTranscription": { "value": { "_version": "20250820", "question_name_xpath": { "manual_transcription": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_dateAccepted": "2025-01-01T12:00:00Z", "_uuid": "11111111-1111-1111-1111-111111111111", "_data": { "language": "fr", "value": "Bonjour" } } ] } } }, "summary": "Manual Transcription" }, "ManualTranscription(with\"locale\")": { "value": { "_version": "20250820", "question_name_xpath": { "manual_transcription": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_dateAccepted": "2025-01-01T12:00:00Z", "_uuid": "11111111-1111-1111-1111-111111111111", "_data": { "language": "fr", "locale": "fr-CA", "value": "Bonjour" } } ] } } }, "summary": "Manual Transcription (with \"locale\")" }, "ManualTranslation": { "value": { "_version": "20250820", "question_name_xpath": { "manual_translation": { "en": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_dateAccepted": "2025-01-01T12:00:00Z", "_uuid": "22222222-2222-2222-2222-222222222222", "_data": { "language": "en", "value": "Hello" }, "_dependency": { "_actionId": "manual_transcription", "_uuid": "11111111-1111-1111-1111-111111111111" } } ] }, "es": { "_dateCreated": "2025-01-01T12:01:00Z", "_dateModified": "2025-01-01T12:01:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:01:00Z", "_dateAccepted": "2025-01-01T12:01:00Z", "_uuid": "33333333-3333-3333-3333-333333333333", "_data": { "language": "es", "value": "Hola" }, "_dependency": { "_actionId": "manual_transcription", "_uuid": "11111111-1111-1111-1111-111111111111" } } ] } } } }, "summary": "Manual Translation" }, "AutomatedGoogleTranscription": { "value": { "_version": "20250820", "question_name_xpath": { "automated_google_transcription": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:01:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:01:00Z", "_uuid": "44444444-4444-4444-4444-444444444444", "_data": { "language": "en", "status": "complete", "value": "Hello world" }, "_dateAccepted": "2025-01-01T12:01:00Z" }, { "_dateCreated": "2025-01-01T12:00:00Z", "_uuid": "44444444-4444-4444-4444-444444444444", "_data": { "language": "en", "status": "in_progress" } } ] } } }, "summary": "Automated Google Transcription" }, "AutomatedGoogleTranslation": { "value": { "_version": "20250820", "question_name_xpath": { "automated_google_translation": { "fr": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:03:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:03:00Z", "_dateAccepted": "2025-01-01T12:03:00Z", "_uuid": "88888888-8888-8888-8888-888888888888", "_data": { "language": "fr", "status": "complete", "value": "Bonjour le monde" }, "_dependency": { "_actionId": "automatic_google_transcription", "_uuid": "44444444-4444-4444-4444-444444444444" } }, { "_dateCreated": "2025-01-01T12:02:00Z", "_uuid": "77777777-7777-7777-7777-777777777777", "_data": { "language": "fr", "status": "in_progress" }, "_dependency": { "_actionId": "automatic_google_transcription", "_uuid": "44444444-4444-4444-4444-444444444444" } }, { "_dateCreated": "2025-01-01T12:01:00Z", "_uuid": "66666666-6666-6666-6666-666666666666", "_data": { "language": "fr", "value": null, "status": "deleted" }, "_dependency": { "_actionId": "automatic_google_transcription", "_uuid": "44444444-4444-4444-4444-444444444444" } }, { "_dateCreated": "2025-01-01T12:00:00Z", "_uuid": "55555555-5555-5555-5555-555555555555", "_data": { "language": "fr", "status": "complete", "value": "Allo la foule" }, "_dependency": { "_actionId": "automatic_google_transcription", "_uuid": "44444444-4444-4444-4444-444444444444" } } ] } } } }, "summary": "Automated Google Translation" }, "QualitativeAnalysis–IntegerQuestion": { "value": { "_version": "20250820", "question_name_xpath": { "": { "66666666-6666-6666-6666-666666666666": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_data": { "uuid": "66666666-6666-6666-6666-666666666666", "value": 42, "status": "complete" }, "_uuid": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", "verified": false } ] } } } }, "summary": "Qualitative Analysis – Integer Question", "description": "`` can be either `manual_qual` or `automatic_bedrock_qual`. \n\n`status` will only be present for automatic_actions." }, "QualitativeAnalysis–TextQuestion": { "value": { "_version": "20250820", "question_name_xpath": { "": { "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_data": { "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeffffffff", "value": "This is a qualitative text response.", "status": "complete" }, "_uuid": "12121212-3434-5656-7878-909090909090", "verified": false } ] } } } }, "summary": "Qualitative Analysis – Text Question", "description": "`` can be either `manual_qual` or `automatic_bedrock_qual`. \n\n`status` will only be present for automatic_actions." }, "QualitativeAnalysis–SingleChoiceQuestion": { "value": { "_version": "20250820", "question_name_xpath": { "": { "77777777-7777-7777-7777-777777777777": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_data": { "uuid": "77777777-7777-7777-7777-777777777777", "value": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", "status": "complete" }, "_uuid": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", "verified": false } ] } } } }, "summary": "Qualitative Analysis – Single Choice Question", "description": "`` can be either `manual_qual` or `automatic_bedrock_qual`. \n\n`status` will only be present for automatic_actions." }, "QualitativeAnalysis–MultipleChoiceQuestion": { "value": { "_version": "20250820", "question_name_xpath": { "": { "88888888-8888-8888-8888-888888888888": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_data": { "uuid": "88888888-8888-8888-8888-888888888888", "value": [ "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb" ], "status": "complete" }, "_uuid": "99999999-9999-9999-9999-999999999999", "verified": false } ] } } } }, "summary": "Qualitative Analysis – Multiple Choice Question", "description": "`` can be either `manual_qual` or `automatic_bedrock_qual`. \n\n`status` will only be present for automatic_actions." }, "ManualQualitativeAnalysis–TagsQuestion": { "value": { "_version": "20250820", "question_name_xpath": { "manual_qual": { "bbbbbbbb-cccc-dddd-eeee-ffffffffffff": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_data": { "uuid": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff", "value": [ "urgent", "review", "priority" ] }, "_uuid": "23232323-4545-6767-8989-010101010101", "verified": false } ] } } } }, "summary": "Manual Qualitative Analysis – Tags Question" }, "QualitativeAnalysis–VerifiedResponse": { "value": { "_version": "20250820", "question_name_xpath": { "": { "bbbbbbbb-cccc-dddd-eeee-ffffffffffff": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_dateVerified": "2025-01-01T12:00:00Z", "_data": { "uuid": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff", "status": "complete", "value": 5 }, "_uuid": "23232323-4545-6767-8989-010101010101", "verified": true } ] } } } }, "summary": "Qualitative Analysis – Verified Response", "description": "`` can be either `manual_qual` or `automatic_bedrock_qual`. " }, "AutomaticQualitativeAnalysis–FailedResponse": { "value": { "_version": "20250820", "question_name_xpath": { "automatic_bedrock_qual": { "bbbbbbbb-cccc-dddd-eeee-ffffffffffff": { "_dateCreated": "2025-01-01T12:00:00Z", "_dateModified": "2025-01-01T12:00:00Z", "_versions": [ { "_dateCreated": "2025-01-01T12:00:00Z", "_data": { "uuid": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff", "status": "failed", "error": "Cannot parse response from LLM" }, "_uuid": "23232323-4545-6767-8989-010101010101", "verified": false } ] } } } }, "summary": "Automatic Qualitative Analysis – Failed response" } } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/data/{uid_data}/attachments/": { "get": { "operationId": "api_v2_assets_data_attachments_list", "description": "## Get an asset's attachment using xpath\n\n* `uid_data` can be the primary key of the submission or its `uuid`.\nPlease note that using the `uuid` may match **several** submissions, only\nthe first match will be returned.\n\nUse the `xpath` property to retrieve an attachment.\n\n```curl\ncurl -X GET https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/data/451/attachment/?xpath=Upload_a_file\n```\n\n### Get an MP3 file from an audio or video file\nConvert audio and video files. Only conversions to MP3 is supported for this feature\n\n```curl\ncurl -X GET https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/data/451/attachment/?xpath=Upload_a_file&format=mp3\n```\n", "parameters": [ { "in": "query", "name": "format", "schema": { "type": "string", "enum": [ "mp3" ] } }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_data", "schema": { "type": "string" }, "description": "UID of the parent data", "required": true }, { "in": "query", "name": "xpath", "schema": { "type": "string" }, "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "description": "Will return a content type with the type of the attachment as well as the attachment itself." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/data/{uid_data}/attachments/{id}/": { "get": { "operationId": "attachment_retrieve", "description": "## Get an asset's attachment using the ID\n\n* `uid_data` can be the primary key of the submission or its `uuid`.\nPlease note that using the `uuid` may match **several** submissions, only\nthe first match will be returned.\n\n* `id` of attachment can be the primary key of the attachment or its `uid`.\n\nBoth examples works:\n```curl\ncurl -X GET https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/data/451/attachment/1/\n```\nOr, using the `UID`:\n```curl\ncurl -X GET https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/data/451/attachment/attwYwGxdtQPSqgmHk6wS6E6/\n```\n\n### Get an MP3 file from an audio or video file\nConvert audio and video files. Only conversions to MP3 is supported for this feature\n\n```curl\ncurl -X GET https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/data/451/attachment/1/?format=mp3\n```\n", "parameters": [ { "in": "query", "name": "format", "schema": { "type": "string", "enum": [ "mp3" ] } }, { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "ID of the attachment", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_data", "schema": { "type": "string" }, "description": "UID of the parent data", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "description": "Will return a content type with the type of the attachment as well as the attachment itself." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/data/{uid_data}/attachments/{id}/{suffix}/": { "get": { "operationId": "attachment_thumbnail", "description": "## Get a specific size of the user's attachment (Only for images)\n\nAvailable formats:\n- `small`\n- `medium`\n- `large`\n\n`id` of attachment can be the primary key of the attachment or its `uid`.\n\nBoth examples works:\n```curl\ncurl -X GET https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/data/451/attachment/1/small/\n```\nOr, using the `UID`:\n```curl\ncurl -X GET https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/data/451/attachment/attwYwGxdtQPSqgmHk6wS6E6/medium/\n```\n", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "ID of the attachment", "required": true }, { "in": "path", "name": "suffix", "schema": { "type": "string", "pattern": "^(original|large|medium|small)$" }, "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_data", "schema": { "type": "string" }, "description": "UID of the parent data", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "description": "Will return a content type with the type of the attachment as well as the attachment itself in the demanded format." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/data/bulk/": { "patch": { "operationId": "api_v2_assets_data_bulk_partial_update", "description": "## Bulk updating of submissions\n\nWhere `` is a string and should be an existing XML field value of the submissions.\nIf `` is part of a group or nested group, the field must follow the group hierarchy\nstructure, i.e.:\n\nIf the field is within a group called `group_1`, the field name is `question_1` and the new value is `new value`,\nthe payload should contain an item with the following structure:\n\n*\"group_1/question_1\": \"new value\"*\n\n\nSimilarly, if there are `N` nested groups, the structure will be:\n\n*\"group_1/sub_group_1/.../sub_group_n/question_1\": \"new value\"*\n", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "ID of the data (when applicable)", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedDataBulkUpdate" } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataBulkUpdateResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "delete": { "operationId": "api_v2_assets_data_bulk_destroy", "description": "## Bulk delete submissions\n\n```curl\n curl -X DELETE https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/data/bulk/\n```\n\n**Payload**\n```json\n{\n \"submissions_ids\": [\n 1,\n 2\n ]\n }\n```\n* Where: `submissions_ids` (required) is a list of submission root id on the data\nto delete\n\n\n**Response**\n```json\n{\n \"detail\": \"{number_of_submissions} submissions have been deleted\"\n}\n```\n* Where: `number_of_submissions` is the number of items that was deleted\n\n\n_Due to limitations with DRF-Spectacular current version, `DELETE` actions do not support showing a request body OR a response body. This is due to the 'vague' nature of the action which generally does *not* recommend the use of a payload. To still document this endpoint, example for the payload and response will be included but it will not be possible to test this endpoint. The HTTP code and the errors example are, for their part, factual and can be considered when working with the endpoint._\n", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "ID of the data (when applicable)", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "description": "No response body" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/data/supplements/bulk/": { "post": { "operationId": "api_v2_assets_data_supplements_bulk_create", "description": "## Bulk accept NLP results\n\nAccepts transcription or translation results for multiple submissions in a\nsingle request. This is the bulk counterpart of the per-submission acceptance\nflow: instead of visiting each submission individually, users can select\nmultiple submissions and approve all of them at once.\n\nThe `operation` field declares the operation to perform. Currently only `\"accept\"`\nis supported.\n\n### Transcription example\n\n```json\n{\n \"submission_uids\": [\"\", \"\"],\n \"question_xpath\": \"group_name/audio_question\",\n \"action_id\": \"automatic_google_transcription\",\n \"operation\": \"accept\"\n}\n```\n\n### Translation example\n\nFor translation actions the `language` field is **required**:\n\n```json\n{\n \"submission_uids\": [\"\", \"\"],\n \"question_xpath\": \"group_name/audio_question\",\n \"action_id\": \"automatic_google_translation\",\n \"language\": \"fr\",\n \"operation\": \"accept\"\n}\n```\n\n### Response\n\nReturns the number of submission records that were successfully accepted.\nSubmissions without a completed NLP result for the given question/action are\nsilently skipped and excluded from the count.\n\n```json\n{\n \"accepted_count\": 472\n}\n```\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAcceptRequest" }, "examples": { "BulkAcceptTranscriptionResults": { "value": { "submission_uids": [ "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "0ca3624a-6f22-451e-8d0a-c40978fd6fe2" ], "question_xpath": "q1_audio", "action_id": "automatic_google_transcription", "operation": "accept" }, "summary": "Bulk accept transcription results" }, "BulkAcceptTranslationResults": { "value": { "submission_uids": [ "3c3f8e07-d660-4f5d-bb0d-7f7a54f02f8f", "0ca3624a-6f22-451e-8d0a-c40978fd6fe2" ], "question_xpath": "q1_audio", "action_id": "automatic_google_translation", "language": "fr", "operation": "accept" }, "summary": "Bulk accept translation results" } } } }, "required": true }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkAcceptResponse" }, "examples": { "BulkAcceptResponse": { "value": { "accepted_count": 472 }, "summary": "Bulk accept response" } } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/data/validation_statuses/": { "patch": { "operationId": "api_v2_assets_data_validation_statuses_partial_update", "description": "## Bulk update submissions status\n\n* Where: \"submissions_ids\" (required) is a list of submission root id on the data\nto delete\n* Where: \"validation_status.uid\" (required) is a string and can be one of these values:\n * `validation_status_approved`\n * `validation_status_not_approved`\n * `validation_status_on_hold`\n\nWill return the number of submission updated as such:\n> **Response**\n>\n> {\n> \"detail\": \"{number_of_submissions} submissions have been updated\"\n> }\n", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "ID of the data (when applicable)", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedDataValidationStatusesUpdatePayload" } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataStatusesUpdate" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "delete": { "operationId": "api_v2_assets_data_validation_statuses_destroy", "description": "## Bulk delete submissions status\n\n```curl\n curl -X DELETE https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/data/validation_statuses/\n```\n\n**Payload**\n```json\n{\n \"payload\": {\n \"submission_ids\": [\n 1,\n 2\n ],\n \"validation_status.uid\": \"validation_status\"\n }\n}\n```\n* Where: \"submissions_ids\" (required) is a list of submission root id on the data\nto delete\n\nThe validation status of the submission can be updated. The `validation_status.uid` should be a `string`, and it must be one of the following values:\n- `validation_status_approved`\n- `validation_status_not_approved`\n- `validation_status_on_hold`\n\n**Response**\n```json\n{\n \"detail\": \"{number_of_submissions} submissions have been updated\"\n}\n```\n\n_Due to limitations with DRF-Spectacular current version, `DELETE` actions do not support showing a request body OR a response body. This is due to the 'vague' nature of the action which generally does *not* recommend the use of a payload. To still document this endpoint, example for the payload and response will be included but it will not be possible to test this endpoint. The HTTP code and the errors example are, for their part, factual and can be considered when working with the endpoint._\n", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "ID of the data (when applicable)", "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "204": { "description": "No response body" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/deployment/": { "get": { "operationId": "api_v2_assets_deployment_retrieve", "description": "## Retrieve the existing deployment (if any)\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "required": true } ], "tags": [ "Manage projects and library content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "post": { "operationId": "api_v2_assets_deployment_create", "description": "## (Re)Deploy a form\n\nDeploy a new form or re-deploy an existing one.\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "required": true } ], "tags": [ "Manage projects and library content" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentCreateRequest" } } }, "required": true }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentResponse" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } }, "patch": { "operationId": "api_v2_assets_deployment_partial_update", "description": "## (Un)Archive the existing deployment.\n\nUpdate the `active` field of the existing deployment.\n\nTo overwrite the entire deployment (including the form contents), use a PUT request.\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "required": true } ], "tags": [ "Manage projects and library content" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedDeploymentPatchRequest" } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentResponse" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/export-settings/": { "get": { "operationId": "api_v2_assets_export_settings_list", "description": "## List of export settings for a specific asset\n\n* _Required permissions: `view_submissions` (View submissions)_\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedExportSettingResponseList" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "post": { "operationId": "api_v2_assets_export_settings_create", "description": "## Create an export setting for an asset\n\n* _Required permissions: `manage_asset` (Manage project)_\n\nWhere:\n\n* `name` (required) is the name of the export setting displayed in the UI\n* `export_settings` (required) is a map of defined settings containing the following valid options:\n * `fields` (optional) is an array of column names to be included in the export (including their group hierarchy). Valid inputs include:\n * An array containing any string value that matches the XML column name\n * An empty array which will result in all columns being included\n * If `fields` is not included in the `export_settings`, all columns will be included in the export\n* `flatten` (optional) is a boolean value and only relevant when exporting to `geojson` format.\n* `fields_from_all_versions` (required) is a boolean to specify whether fields from all form versions will be included in the export.\n* `group_sep` (required) is a value used to separate the names in a hierarchy of groups. Valid inputs include:\n * Non-empty value\n* `hierarchy_in_labels` (required) is a boolean to specify whether the group hierarchy will be displayed in labels\n* `multiple_select` (required) is a value to specify the display of multiple-select-type responses. Valid inputs include:\n * `both`,\n * `summary`, or\n * `details`\n* `type` (required) specifies the export format. Valid export formats include:\n * `csv`,\n * `geojson`,\n * `spss_labels`, or\n * `xls`\n* `xls_types_as_text` (optional) is a boolean value that defaults to `false` and only affects `xls` export types.\n* `include_media_url` (optional) is a boolean value that defaults to `false` and only affects `xls` and `csv` export types.\n* `submission_ids` (optional) is an array of submission ids that will filter exported submissions to only the specified array of ids. Valid inputs include:\n * An array containing integer values\n * An empty array (no filtering)\n* `query` (optional) is a JSON object containing a Mongo filter query for filtering exported submissions. Valid inputs include:\n * A JSON object containing a valid Mongo query\n * An empty JSON object (no filtering)\n\n**Note that the following behaviour can be expected when specifying a value for the `multiple_select` field:**\n\n* `summary`: Includes one column per question, with all selected choices separated by spaces;\n* `details`: Expands each multiple-select question to one column per choice, with each of those columns having a binary 1 or 0 to indicate whether that choice was chosen;\n* `both`: Includes the format of `summary` _and_ `details` in the export\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportSettingCreatePayload" } } }, "required": true }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportSettingResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/export-settings/{uid_export_setting}/": { "get": { "operationId": "api_v2_assets_export_settings_retrieve", "description": "## Retrieve a specific export setting\n\n* _Required permissions: `view_submissions` (View submissions)_\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_export_setting", "schema": { "type": "string" }, "description": "UID of the export-settings", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportSettingResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "patch": { "operationId": "api_v2_assets_export_settings_partial_update", "description": "## Update the current export setting\n\n* _Required permissions: `manage_asset` (Manage project)_\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_export_setting", "schema": { "type": "string" }, "description": "UID of the export-settings", "required": true } ], "tags": [ "Survey data" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedExportSettingUpdatePayload" } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportSettingResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } }, "delete": { "operationId": "api_v2_assets_export_settings_destroy", "description": "## Delete current export setting\n\n* _Required permissions: `manage_asset` (Manage project)_\n\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_export_setting", "schema": { "type": "string" }, "description": "UID of the export-settings", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "204": { "description": "No response body" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/export-settings/{uid_export_setting}/data/": { "get": { "operationId": "api_v2_assets_export_settings_data_retrieve", "description": "## Synchronously export data\n\nTo retrieve data synchronously in CSV and XLSX format according to a\nparticular instance of export settings.\n\nProcessing time of synchronous exports is substantially limited compared to\nasynchronous exports, which are available at `/api/v2/assets/{asset_uid}/exports/`.\n", "parameters": [ { "in": "query", "name": "format", "schema": { "type": "string", "enum": [ "csv", "xlsx" ] }, "required": true }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_export_setting", "schema": { "type": "string" }, "description": "UID of the export-settings", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "description": "Will return a content type with the type of the attachment as well as the attachment itself." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/exports/": { "get": { "operationId": "api_v2_assets_exports_list", "description": "## List of export tasks endpoints\n\nLists the export tasks accessible to requesting user, for anonymous access\nnothing is returned.\n\n* _Required permissions: `view_submissions` (View submissions)_\n\nOtherwise, the search can be more specific:\n\n**Exports matching `uid`s:**\n```shell\ncurl -X GET https://kf.kobotoolbox.org/api/v2/assets/{asset_uid}/exports/?q=uid__in:ehZUwRctkhp9QfJgvEWGg OR uid__in:ehZUwRctkhp9QfJgvDnjud\n```\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "ordering", "required": false, "in": "query", "description": "Which field to use when ordering the results.", "schema": { "type": "string" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedExportResponseList" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "post": { "operationId": "api_v2_assets_exports_create", "description": "## Creates an export task\n\nWhere:\n* `fields_from_all_versions` (required) is a boolean to specify whether fields from all form versions will be included in the export.\n * `group_sep` (required) is a value used to separate the names in a hierarchy of groups. Valid inputs include:\n * Non-empty value\n * `hierarchy_in_labels` (required) is a boolean to specify whether the group hierarchy will be displayed in labels\n * `lang` (required) is a string that can be set to:\n * `_xml` to have XML values and headers, or\n * Any translation specified in the form such as `English (en)`, etc.\n * `multiple_select` (required) is a value to specify the display of `multiple_select-type` responses. Valid inputs include:\n * `both`,\n * `summary`, or\n * `details`\n * \"`type`\" (required) specifies the export format. Valid export formats include:\n * `csv`,\n * `geojson`,\n * `spss_labels`, or\n * `xls`\n * `fields` (optional) is an array of column names to be included in the export (including their group hierarchy). Valid inputs include:\n * An array containing any string value that matches the XML column name\n * An empty array which will result in all columns being included\n * If `fields` is not included in the `export_settings`, all columns will be included in the export\n * `flatten` (optional) is a boolean value and only relevant when exporting to \"geojson\" format.\n * `xls_types_as_text` (optional) is a boolean value that defaults to `false` and only affects `xls` export types.\n * `include_media_url` (optional) is a boolean value that defaults to `false` and only affects `xls` and \"csv\" export types. This will include an additional column for media-type questions (`question_name_URL`) with the URL link to the hosted file.\n * `submission_ids` (optional) is an array of submission ids that will filter exported submissions to only the specified array of ids. Valid inputs include:\n * An array containing integer values\n * An empty array (no filtering)\n * `query` (optional) is a JSON object containing a Mongo filter query for filtering exported submissions. Valid inputs include:\n * A JSON object containing a valid Mongo query\n * An empty JSON object (no filtering)\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportCreatePayload" } } }, "required": true }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/exports/{uid_export}/": { "get": { "operationId": "api_v2_assets_exports_retrieve", "description": "## Retrieves current export task\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_export", "schema": { "type": "string" }, "description": "UID of the export task", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "delete": { "operationId": "api_v2_assets_exports_destroy", "description": "## Deletes current export task\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_export", "schema": { "type": "string" }, "description": "UID of the export task", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "204": { "description": "No response body" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/files/": { "get": { "operationId": "api_v2_assets_files_list", "description": "## Retrieve current asset files\n\nResults can be narrowed down with a filter by type:\n```shell\ncurl -X GET https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/files/?collections_first=true&ordering=-name\n```\n", "parameters": [ { "name": "file_type", "required": false, "in": "query", "description": "Filter files by type (e.g., \"form_media\")", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedFilesResponseList" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "post": { "operationId": "api_v2_assets_files_create", "description": "## Create a new file on current asset\n\nFields:\n\n- `asset` (required)\n- `user` (required)\n- `description` (required)\n- `file_type` (required)\n- `content` (as binary) (optional)\n- `metadata` JSON (optional)\n\n_Notes:_\n\n1. Files can have different types:\n - `map_layer`\n - `form_media`\n2. Files can be created with three different ways\n - `POST` a file with `content` parameter\n - `POST` a base64 encoded string with `base64Encoded` parameter1\n - `POST` an URL with `metadata` parameter2\n\n1) `metadata` becomes mandatory and must contain `filename` property
\n2) `metadata` becomes mandatory and must contain `redirect_url` property\n\n**Files with `form_media` type must have unique `filename` per asset**\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFilePayload" }, "examples": { "CreatingAFileWithBinaryContent": { "value": { "description": "Description of the file", "file_type": "form_media", "content": "" }, "summary": "Creating a file with binary content" }, "CreatingAFileWithBase64Content": { "value": { "description": "Description of the file", "file_type": "form_media", "base64Encoded": "SGVsbG8sIFdvcmxkIQ", "metadata": { "filename": "string" } }, "summary": "Creating a file with Base64 content" }, "CreatingAFileWithARemoteUrl": { "value": { "description": "Description of the file", "file_type": "form_media", "metadata": { "redirect_url": "string" } }, "summary": "Creating a file with a remote url" } } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/files/{uid_file}/": { "get": { "operationId": "api_v2_assets_files_retrieve", "description": "## Retrieve a file from current asset\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_file", "schema": { "type": "string" }, "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilesResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "delete": { "operationId": "api_v2_assets_files_destroy", "description": "## Delete a file from current asset\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_file", "schema": { "type": "string" }, "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "204": { "description": "No response body" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/files/{uid_file}/content/": { "get": { "operationId": "api_v2_assets_files_content_retrieve", "description": "## Download the asset file\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_file", "schema": { "type": "string" }, "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "description": "Will return a content type with the type of the attachment as well as the attachment itself." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/history/": { "get": { "operationId": "api_v2_assets_history_list", "description": "## List project history logs\n\nLists all project history logs for a single project.\n\n⚠️ _Required permissions: `manage_asset` (Manage project)_\n\nResults from this endpoint can be filtered by a Boolean query specified in the `q` parameter.\n\n### Filterable fields for all project history logs:\n\n - date_created\n - user_uid\n - user__username\n - user__email\n - user__is_superuser\n - metadata__source\n - metadata__ip_address\n - metadata__log_subtype\n - available subtypes: \"project\", \"permission\"\n\n### action\n\navailable actions:\n - add-media\n - add-submission\n - allow-anonymous-submissions\n - archive\n - clone-permissions\n - connect-project\n - delete-media\n - delete-service\n - delete-submission\n - deploy\n - disable-sharing\n - disallow-anonymous-submissions\n - disconnect-project\n - enable-sharing\n - export\n - modify-imported-fields\n - modify-qa-data\n - modify-service\n - modify-sharing\n - modify-submission\n - modify-user-permissions\n - redeploy\n - register-service\n - replace-form\n - share-data-publicly\n - share-form-publicly\n - transfer\n - unarchive\n - unshare-data-publicly\n - unshare-form-publicly\n - update-content\n - update-name\n - update-settings\n - update-qa\n\n### Filterable fields by action:\n\n add-media\n - metadata__asset-file__uid\n - metadata__asset-file__filename\n\n add-submission\n - metadata__submission__submitted_by\n - metadata__submission__root_uuid\n\n archive\n - metadata__latest_version_uid\n\n clone-permissions\n - metadata__cloned_from\n\n connect-project\n - metadata__paired-data__source_uid\n - metadata__paired-data__source_name\n\n delete-media\n - metadata__asset-file__uid\n - metadata__asset-file__filename\n\n delete-service\n - metadata__hook__uid\n - metadata__hook__endpoint\n - metadata__hook__active\n\n delete-submission\n - metadata__submission__submitted_by\n - metadata__submission__root_uuid\n\n deploy\n - metadata__latest_version_uid\n - metadata__latest_deployed_version_uid\n\n disconnect-project\n - metadata__paired-data__source_uid\n - metadata__paired-data__source_name\n\n modify-imported-fields\n - metadata__paired-data__source_uid\n - metadata__paired-data__source_name\n\n modify-qa-data\n - metadata__submission__submitted_by\n - metadata__submission__root_uuid\n\n modify-service\n - metadata__hook__uid\n - metadata__hook__endpoint\n - metadata__hook__active\n\n modify-submission\n - metadata__submission__submitted_by\n - metadata__submission__root_uuid\n - metadata__submission__status (only present if changed)\n\n modify-user-permissions\n - metadata__permissions__username\n\n redeploy\n - metadata__latest_version_uid\n - metadata__latest_deployed_version_uid\n\n register-service\n - metadata__hook__uid\n - metadata__hook__endpoint\n - metadata__hook__active\n\n transfer\n - metadata__username\n\n unarchive\n - metadata__latest_version_uid\n\n update-name\n - metadata__name__old\n - metadata__name__new\n\n update-settings\n - metadata__settings__description__old\n - metadata__settings__description__new\n\nThis endpoint can be paginated with 'start' and 'limit' parameters.\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "in": "query", "name": "q", "schema": { "type": "string" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent assets", "required": true } ], "tags": [ "Logging" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedHistoryListResponseList" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/history/actions/": { "get": { "operationId": "api_v2_assets_history_actions_retrieve", "description": "## Retrieve distinct actions performed on the project.\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent assets", "required": true } ], "tags": [ "Logging" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryActionResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/history/export/": { "post": { "operationId": "api_v2_assets_history_export_create", "description": "## Export current project's history\n\nExports the project's history and sends it by email to the requesting user.\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent assets", "required": true } ], "tags": [ "Logging" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/historyExportResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/hooks/": { "get": { "operationId": "api_v2_assets_hooks_list", "description": "## List external services\n\nLists the external services endpoints accessible to requesting user\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent assets", "required": true } ], "tags": [ "Survey data - Rest Services" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedHookList" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "post": { "operationId": "api_v2_assets_hooks_create", "description": "## Add an external service to asset.\n\nWhere:\n\n* `name` and `endpoint` are required\n* `active` is True by default\n* `export_type` must be one of these values:\n\n 1. `json` (_default_)\n 2. `xml`\n\n* `email_notification` is a boolean. If true, User will be notified when request to remote server has failed.\n* `auth_level` must be one of these values:\n\n 1. `no_auth` (_default_)\n 2. `basic_auth`\n\n* `subset_fields` is the list of fields of the form definition. Only these fields should be present in data sent to remote server\n* `settings`.`custom_headers` is dictionary of `custom header`: `value`\n\nFor example:\n> \"settings\": {\n> \"customer_headers\": {\n> \"Authorization\" : \"Token 1af538baa9045a84c0e889f672baf83ff24\"\n> }\n\n* `payload_template` is a custom wrapper around `%SUBMISSION%` when sending data to remote server.\n It can be used only with JSON submission format.\n\nFor example:\n> \"payload_template\": '{\"fields\": %SUBMISSION%}'\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent assets", "required": true } ], "tags": [ "Survey data - Rest Services" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hook" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/Hook" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/Hook" } } }, "required": true }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hook" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/hooks/{uid_hook}/": { "get": { "operationId": "api_v2_assets_hooks_retrieve", "description": "## Retrieve an external service\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent assets", "required": true }, { "in": "path", "name": "uid_hook", "schema": { "type": "string" }, "description": "UID of the hook", "required": true } ], "tags": [ "Survey data - Rest Services" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hook" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "patch": { "operationId": "api_v2_assets_hooks_partial_update", "description": "## Update an external service.\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent assets", "required": true }, { "in": "path", "name": "uid_hook", "schema": { "type": "string" }, "description": "UID of the hook", "required": true } ], "tags": [ "Survey data - Rest Services" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedHook" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PatchedHook" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PatchedHook" } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hook" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } }, "delete": { "operationId": "api_v2_assets_hooks_destroy", "description": "## Delete an external service.\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent assets", "required": true }, { "in": "path", "name": "uid_hook", "schema": { "type": "string" }, "description": "UID of the hook", "required": true } ], "tags": [ "Survey data - Rest Services" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "204": { "description": "No response body" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/hooks/{uid_hook}/logs/": { "get": { "operationId": "api_v2_assets_hooks_logs_list", "description": "## List logs of an external services endpoints accessible to requesting user\n\n⚠️ The `page` query parameter is deprecated, use `start` and `limit` instead.\n\nWhere:\n* `asset_uid` - is the unique identifier of a specific asset\n* `hook_uid` - is the unique identifier of a specific external service\n* `uid` - is the unique identifier of a specific log\n\nUse the `status` query parameter to filter logs by numeric status:\n* `status=0`: hook has failed after exhausting all retries\n* `status=1`: hook is still pending\n* `status=2`: hook has succeeded\n\nUse the `start_date` and `end_date` query parameters to filter logs by date range,\nproviding ISO-8601 date strings (e.g. '2022-01-14', '2022-01-21 06:51:04',\n'2022-01-21T06:51:08.144004+02:00'). Time zone is assumed to be UTC. If provided, it\nneeds to be in '+00:00' format ('Z' is not supported). Watch out for url encoding for\nthe '+' character (%2B).\n\nNote that `start_date` is inclusive, while `end_date` is exclusive.\n", "parameters": [ { "in": "query", "name": "end_date", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } }, { "in": "query", "name": "start_date", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "status", "schema": { "type": "integer", "enum": [ 0, 1, 2, 3 ] }, "description": "* `0` - failed\n* `1` - pending\n* `3` - processing\n* `2` - success" }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent assets", "required": true }, { "in": "path", "name": "uid_hook", "schema": { "type": "string" }, "description": "UID of the parent hook", "required": true } ], "tags": [ "Survey data - Rest Services" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedHookLogList" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/hooks/{uid_hook}/logs/{uid_log}/": { "get": { "operationId": "api_v2_assets_hooks_logs_retrieve", "description": "## Retrieve an external service endpoint log\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent assets", "required": true }, { "in": "path", "name": "uid_hook", "schema": { "type": "string" }, "description": "UID of the parent hook", "required": true }, { "in": "path", "name": "uid_log", "schema": { "type": "string" }, "required": true } ], "tags": [ "Survey data - Rest Services" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HookLog" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/hooks/{uid_hook}/logs/{uid_log}/retry/": { "patch": { "operationId": "api_v2_assets_hooks_logs_retry_partial_update", "description": "## Retry a failed submission attempt\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent assets", "required": true }, { "in": "path", "name": "uid_hook", "schema": { "type": "string" }, "description": "UID of the parent hook", "required": true }, { "in": "path", "name": "uid_log", "schema": { "type": "string" }, "required": true } ], "tags": [ "Survey data - Rest Services" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedHookLog" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PatchedHookLog" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PatchedHookLog" } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogsRetryResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/hooks/{uid_hook}/retry/": { "patch": { "operationId": "api_v2_assets_hooks_retry_partial_update", "description": "## Retries all failed attempts\n\n**This call is asynchronous. Job is sent to Celery to be run in background**\n\nIt returns all logs `uid`s that are being retried.\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent assets", "required": true }, { "in": "path", "name": "uid_hook", "schema": { "type": "string" }, "description": "UID of the hook", "required": true } ], "tags": [ "Survey data - Rest Services" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HookRetryResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/paired-data/": { "get": { "operationId": "api_v2_assets_paired_data_list", "description": "## List paired project endpoints\n\nThis endpoint is paginated and accepts these parameters:\n- `offset`: The initial index from which to return the results\n- `limit`: Number of results to return per page\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedPairedDataResponseList" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "post": { "operationId": "api_v2_assets_paired_data_create", "description": "## Create a connection between two projects\n\n* `fields`: Optional. List of questions whose responses will be retrieved\n from the source data. If missing or empty, all responses will be\n retrieved. Questions must be identified by full group path separated by\n slashes, e.g. `group/subgroup/question_name`.\n* `filename`: Must be unique among all asset files. Only accepts letters, numbers and '-'.\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Survey data" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairedData" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PairedData" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PairedData" } } }, "required": true }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairedDataResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/paired-data/{uid_paired_data}/": { "get": { "operationId": "api_v2_assets_paired_data_retrieve", "description": "## Retrieve a connection between two projects\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_paired_data", "schema": { "type": "string" }, "description": "UID of the paired data", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairedDataResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "patch": { "operationId": "api_v2_assets_paired_data_partial_update", "description": "## Update a connection between two projects\n\n_Notes: `source` cannot be changed_\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_paired_data", "schema": { "type": "string" }, "description": "UID of the paired data", "required": true } ], "tags": [ "Survey data" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedPairedDataPatchPayload" } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairedDataResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } }, "delete": { "operationId": "api_v2_assets_paired_data_destroy", "description": "## Remove a connection between two projects\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_paired_data", "schema": { "type": "string" }, "description": "UID of the paired data", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "204": { "description": "No response body" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/paired-data/{uid_paired_data}/external/": { "get": { "operationId": "api_v2_assets_paired_data_external_retrieve", "description": "## Return an XML which contains data submitted to paired asset\n\nCreates the endpoints\n- /api/v2/assets//paired-data//external/\n- /api/v2/assets//paired-data//external.xml/\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_paired_data", "schema": { "type": "string" }, "description": "UID of the paired data", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/xml": { "schema": { "$ref": "#/components/schemas/ExternalResponse" } } }, "description": null }, "404": { "content": { "application/xml": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/permission-assignments/": { "get": { "operationId": "api_v2_assets_permission_assignments_list", "description": "## List permission assignments\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Manage permissions" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionAssignmentResponse" } } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "post": { "operationId": "api_v2_assets_permission_assignments_create", "description": "## Assign a permission\n\nN.B.:\n - Filters use Mongo Query Engine to narrow down results\n - Filters are joined with `OR` operator\n - Implied permissions will be also assigned. (e.g. `change_asset` will add `view_asset` too)\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Manage permissions" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionAssignmentCreateRequest" }, "examples": { "CreatePartialPermission": { "value": { "user": "https://kf.kobotoolbox.org/api/v2/users/bob/", "partial_permission": [ { "filter": [ { "_submitted_by": { "$in": [ "string" ] } } ], "url": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/permission-assignments/pGaXCTDAbdZKLXoXAXd3M4/" } ], "permission": "https://kf.kobotoolbox.org/api/v2/permissions/change_asset/" }, "summary": "Create partial permission" }, "CreatePermission": { "value": { "user": "https://kf.kobotoolbox.org/api/v2/users/bob/", "permission": "https://kf.kobotoolbox.org/api/v2/permissions/change_asset/" }, "summary": "Create permission" } } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionAssignmentResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/permission-assignments/{uid_permission_assignment}/": { "get": { "operationId": "api_v2_assets_permission_assignments_retrieve", "description": "## Retrieve assignments\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_permission_assignment", "schema": { "type": "string" }, "description": "UID of the permission", "required": true } ], "tags": [ "Manage permissions" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionAssignmentResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "delete": { "operationId": "api_v2_assets_permission_assignments_destroy", "description": "## Remove a permission assignment\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_permission_assignment", "schema": { "type": "string" }, "description": "UID of the permission", "required": true } ], "tags": [ "Manage permissions" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "204": { "description": "No response body" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/permission-assignments/bulk/": { "post": { "operationId": "api_v2_assets_permission_assignments_bulk_create", "description": "## Assign multiple permissions at once\n\n* Can put both regular and partial permission in the payload\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Manage permissions" ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionAssignmentBulkRequest" } } } }, "required": true }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionAssignmentResponse" } } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } }, "delete": { "operationId": "api_v2_assets_permission_assignments_bulk_destroy", "description": "## Remove all permission assignments\n\n⚠️ **Warning**\nThis endpoint currently supports deleting **only the user whose username is provided as a parameter**.\nDeletion of other accounts is not yet supported.\n\n**Payload**\n```json\n{\n \"username\": \"bob\"\n}\n```\n\n_Due to limitations with DRF-Spectacular current version, `DELETE` actions do not support showing a request body OR a response body. This is due to the 'vague' nature of the action which generally does *not* recommend the use of a payload. To still document this endpoint, example for the payload and response will be included but it will not be possible to test this endpoint. The HTTP code and the errors example are, for their part, factual and can be considered when working with the endpoint._\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Manage permissions" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "204": { "description": "No response body" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/permission-assignments/clone/": { "patch": { "operationId": "api_v2_assets_permission_assignments_clone_partial_update", "description": "## Clone permission assignments from another asset using uid\n\nWhere `clone_from` is the source uid.\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Manage permissions" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedPermissionAssignmentCloneRequest" } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionAssignmentResponse" } } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/qual-questions/{uid_qa_question}/tags/": { "get": { "operationId": "api_v2_assets_qual_questions_tags_list", "description": "## List available tags for a QA tags question\n\nLists the tag values previously submitted for a `qualTags` question on this asset, sorted alphabetically.\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_qa_question", "schema": { "type": "string" }, "description": "UUID of the QA tags question", "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/QATagTracker" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/reports/": { "get": { "operationId": "api_v2_assets_reports_retrieve", "description": "## Report of a user's asset\n\nReturns the submission data for all deployments of a survey.\nThis data is grouped by answers, and does not show the data for individual submissions.\nThe endpoint will return a **404 NOT FOUND** error if the asset is not deployed and will only return the data for the most recently deployed version.\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "required": true } ], "tags": [ "Survey data" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/table_view/": { "get": { "operationId": "api_v2_assets_table_view_retrieve", "description": "## Return plain HTML of survey in tabular format\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "required": true } ], "tags": [ "Form content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "text/html": { "schema": { "type": "string" }, "examples": { "TableViewExample": { "value": "\n
#survey\n\n| type    | name       | label      | default   | required   |\n|---------+------------+------------+-----------+------------|\n| start   | start      |            |           |            |\n| end     | end        |            |           |            |\n| text    | Question_1 | Question 1 |           | true       |\n| integer | Question_2 | Question 2 |           | false      |\n
\n", "summary": "Expected HTML response" } } } }, "description": "" }, "404": { "description": "No response body" } } } }, "/api/v2/assets/{uid_asset}/valid_content/": { "get": { "operationId": "api_v2_assets_valid_content_retrieve", "description": "## Return valid content for user's asset\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "required": true } ], "tags": [ "Form content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetValidContentResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/versions/": { "get": { "operationId": "api_v2_assets_versions_list", "description": "## List the versions of forms\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } }, { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true } ], "tags": [ "Manage projects and library content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedVersionListResponseList" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/versions/{uid_version}/": { "get": { "operationId": "api_v2_assets_versions_retrieve", "description": "## Retrieve asset versions\n\nReturns the details of an asset version\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "description": "UID of the parent asset", "required": true }, { "in": "path", "name": "uid_version", "schema": { "type": "string" }, "required": true } ], "tags": [ "Manage projects and library content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionRetrieveResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/{uid_asset}/xform/": { "get": { "operationId": "api_v2_assets_xform_retrieve", "description": "## This route will render the XForm into syntax-highlighted HTML.\n\nIt is useful for debugging pyxform transformations\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "required": true } ], "tags": [ "Manage projects and library content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "text/html": { "schema": { "type": "string" }, "examples": { "XFORMExample": { "value": "\n\n \n Project 1 EXAMPLE\n \n \n \n \n This is an example\n \n \n \n \n \n \n \n Example 1\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n\n", "summary": "Expected HTML response" } } } }, "description": "" }, "404": { "description": "No response body" } } } }, "/api/v2/assets/{uid_asset}/xls/": { "get": { "operationId": "api_v2_assets_xls_retrieve", "description": "## Return plain HTML of survey in tabular format\n", "parameters": [ { "in": "path", "name": "uid_asset", "schema": { "type": "string" }, "required": true } ], "tags": [ "Form content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "text/html": { "schema": { "type": "string" }, "examples": { "XLSExample": { "value": "\n
#survey\n\n| type    | name       | label      | default   | required   |\n|---------+------------+------------+-----------+------------|\n| start   | start      |            |           |            |\n| end     | end        |            |           |            |\n| text    | Question_1 | Question 1 |           | true       |\n| integer | Question_2 | Question 2 |           | false      |\n
\n", "summary": "Expected HTML response" } } } }, "description": "" }, "404": { "description": "No response body" } } } }, "/api/v2/assets/bulk/": { "post": { "operationId": "api_v2_assets_bulk_create", "description": "## Perform bulk actions on assets\n\nActions available:\n\n- `archive`\n- `delete`\n- `unarchive`\n- `undelete` (superusers only)\n", "tags": [ "Manage projects and library content" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetBulkRequest" }, "examples": { "PerformActionOnOneOrMoreAsset": { "value": { "asset_uids": { "asset_uids": [ {} ] }, "action": "string" }, "summary": "Perform action on one or more asset" }, "PerformBulkOnALLAsset": { "value": { "confirm": true, "action": "string" }, "summary": "Perform bulk on ALL asset" } } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetBulkResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/assets/counts/": { "get": { "operationId": "api_v2_assets_counts_retrieve", "description": "## Return counts of deployed, archived, and draft assets\n", "tags": [ "Manage projects and library content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetListCount" } } }, "description": null } } } }, "/api/v2/assets/hash/": { "get": { "operationId": "api_v2_assets_hash_retrieve", "description": "## Get a hash of all `version_id`s of all accessible assets by the current user.\n\nUseful to detect any changes in assets with only one call to `API`\n", "tags": [ "Manage projects and library content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HashResponse" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" } } } }, "/api/v2/assets/metadata/": { "get": { "operationId": "api_v2_assets_metadata_retrieve", "description": "## Get metadata for all authenticated user' assets\n", "tags": [ "Manage projects and library content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetMetadataResponse" } } }, "description": null } } } }, "/api/v2/assets/minimal-list/": { "get": { "operationId": "api_v2_assets_minimal_list_retrieve", "description": "## Return a minimal listing of assets with their deployment status\n\nReturns a paginated list of assets visible to the current user, including only `uid`, `name`, and `deployment_status` (`draft`, `deployed`, or `archived`).\n\nUse the `q` query parameter to filter by asset type (e.g. `?q=asset_type:survey`).\n\nResponses do not include a `count` field. Use the `next` and `previous` links to paginate through results.\n", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Number of results to return per page." }, { "in": "query", "name": "q", "schema": { "type": "string" }, "description": "Filter the results with search query" }, { "in": "query", "name": "start", "schema": { "type": "integer" }, "description": "The initial index from which to return the results." } ], "tags": [ "Manage projects and library content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAssetMinimalListList" } } }, "description": null } } } }, "/api/v2/audit-logs/": { "get": { "operationId": "api_v2_audit_logs_list", "description": "## List actions performed by users.\n\n⚠️ _Only available to superusers_\n\nResults from this endpoint can be filtered by a Boolean query specified in the `q` parameter.\n\n**Filterable fields:**\n\n* app_label\n* model_name\n* action\n Available actions:\n * create\n * delete\n * in-trash\n * put-back\n * remove\n * update\n * auth\n* log_type\n Available log types:\n * access\n * project-history\n * data-editing\n * submission-management\n * user-management\n * asset-management\n* date_created\n* user_uid\n* user__username\n* user__email\n* user__is_superuser\n* metadata__asset_uid\n* metadata__auth_type\n\n*Notes: Some logs may have additional filterable fields in the metadata*\n\n**Some examples:**\n\n* All deleted submissions\n `api/v2/audit-logs/?q=action:delete`\n* All deleted submissions of a specific project `aTJ3vi2KRGYj2NytSzBPp7`\n `api/v2/audit-logs/?q=action:delete AND metadata__asset_uid:aTJ3vi2KRGYj2NytSzBPp7`\n* All submissions deleted by a specific user `my_username`\n `api/v2/audit-logs/?q=action:delete AND user__username:my_username`\n* All deleted submissions submitted after a specific date\n `/api/v2/audit-logs/?q=action:delete AND date_created__gte:2022-11-15`\n* All deleted submissions submitted after a specific date **and time**\n `/api/v2/audit-logs/?q=action:delete AND date_created__gte:\"2022-11-15 20:34\"`\n* All authentications from superusers\n `api/v2/audit-logs/?q=action:auth AND user__is_superuser:True`\n\n*Notes: Do not forget to wrap search terms in double-quotes if they contain spaces\n(e.g. date and time \"2022-11-15 20:34\")*\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "in": "query", "name": "q", "schema": { "type": "string" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "Server logs (superusers)" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAuditLogResponseList" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/email-confirmations/": { "post": { "operationId": "api_v2_email_confirmations_create", "description": "## Request another account confirmation email\n\nSends a fresh confirmation link to an email address that is registered but not yet\nverified. Confirmation links expire (after\n`ACCOUNT_EMAIL_CONFIRMATION_EXPIRE_DAYS`, one day by default), so this is how a\nuser who let theirs lapse gets a new one.\n\nRequires no authentication: the caller has just followed a dead confirmation link\nand has no session.\n\nExamples:\n```shell\n curl -X POST https://kf.kobotoolbox.org/api/v2/email-confirmations/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"email\": \"someone@example.com\"}'\n```\n\n> Response 200\n```json\n{\n \"detail\": \"If that email address needs confirming, a new confirmation email has been sent to it.\"\n}\n```\n\n### Which email is sent\n\nAn account that has not verified any address yet is still being activated, and\nreceives the account activation email. An account that already has a verified\naddress is partway through an email change, and receives the address\nverification email instead.\n\n### The response never says whether the address is registered\n\nThe same `200` and the same body come back whether the address belongs to an\naccount, belongs to an account that has already verified it, or belongs to no\naccount at all. Otherwise the endpoint would let anyone test whether a given\nperson holds a KoboToolbox account.\n\nMail goes out only in the first of those cases. An address that is already\nverified is left alone, so this cannot be used to send unsolicited mail to a\nverified account.\n\nA syntactically invalid address returns `400`. That reveals nothing about who is\nregistered, and telling the user their address is malformed is more useful than\nsilently doing nothing.\n\n### Throttling\n\nThe endpoint is rate limited per requested email address, and returns `429` once\nthat limit is reached. Limiting by address rather than by caller means requests\ncannot be spread across many source addresses to flood a single inbox.\n\nThe limit is set by the `EMAIL_CONFIRMATION_REQUESTS_PER_HOUR` configuration\noption, and can be changed by an administrator without a restart.\n", "tags": [ "User / team / organization / usage" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailConfirmationRequestPayload" } } }, "required": true }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, {} ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailConfirmationRequestResponse" }, "examples": { "RequestAccepted": { "value": { "detail": "If that email address needs confirming, a new confirmation email has been sent to it." }, "summary": "Request accepted" } } } }, "description": null }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "TooManyRequests": { "value": { "detail": "Request was throttled. Expected available in 60 seconds." }, "summary": "Too many requests" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "email": [ "Enter a valid email address." ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/environment/": { "get": { "operationId": "api_v2_environment_retrieve", "description": "Retrieve Kobo server environment configurations.\n\nThis endpoint provides a wide range of configuration details required by the frontend client, including:\n- Legal, support, and community URLs (e.g. Terms of Service, Privacy Policy).\n- Frontend configuration (retry times, usage limit enforcement, etc).\n- Global static lists (sectors, countries, interface languages, operational purposes).\n- Metadata configuration (available project and user metadata fields).\n- Features configurations (MFA, password entropy meter, custom guidance text).\n- Sign-in and account creation branding (theme, logos, background and supporting image, supporting text) and behaviour (whether registration is open, whether a username is accepted at sign-in).\n- Additional integrations and features (Stripe public key, ASR & MT enablement, Social apps).\n", "tags": [ "Configuration" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, {} ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentResponse" } } }, "description": null } } } }, "/api/v2/imports/": { "get": { "operationId": "api_v2_imports_list", "description": "## List imported files\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "Manage projects and library content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, {} ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedImportResponseList" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" } } }, "post": { "operationId": "api_v2_imports_create", "description": "## Import file\n\n_**Note**: this endpoint is expecting a multipart/form-data_\n", "tags": [ "Manage projects and library content" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ImportCreateRequest" } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, {} ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportCreateResponse" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/imports/{uid_import}/": { "get": { "operationId": "api_v2_imports_retrieve", "description": "## Retrieve imported files\n", "parameters": [ { "in": "path", "name": "uid_import", "schema": { "type": "string" }, "required": true } ], "tags": [ "Manage projects and library content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, {} ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportResponse" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/languages/": { "get": { "operationId": "api_v2_languages_list", "description": "## List the languages accessible to requesting (authenticated) user.\n\nSearch can be made with `q` parameter. By default, search for the term in language names or language codes.\n\nExamples:\n```shell\n curl -X GET https://kf.kobotoolbox.org/api/v2/languages/?q=fr\n```\n\nComplex searches can be done on other fields, such as `transcription_services` and `translation_services`.\n\nExamples:\n```shell\n curl -X GET https://kf.kobotoolbox.org/api/v2/languages/?q=transcription_services__code:goog AND translation_services__code:goog\n```\n\nResults are order by `featured` first (descending order), then by their name.\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "in": "query", "name": "q", "schema": { "type": "string" }, "description": "Search languages by name or code" }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "Other" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedLanguageListList" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" } } } }, "/api/v2/languages/{code}/": { "get": { "operationId": "api_v2_languages_retrieve", "description": "## Retrieve one language\n\n* `code` - is the unique identifier of a specific language\n", "parameters": [ { "in": "path", "name": "code", "schema": { "type": "string" }, "required": true } ], "tags": [ "Other" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Language" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/organizations/": { "get": { "operationId": "api_v2_organizations_list", "description": "## List user's organizations\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOrganizationResponseList" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/organizations/{uid_organization}/": { "get": { "operationId": "api_v2_organizations_retrieve", "description": "## Retrieve organization's details\n", "parameters": [ { "in": "path", "name": "uid_organization", "schema": { "type": "string" }, "description": "A unique value identifying this organization.", "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "patch": { "operationId": "api_v2_organizations_partial_update", "description": "## Update organization's details\n", "parameters": [ { "in": "path", "name": "uid_organization", "schema": { "type": "string" }, "description": "A unique value identifying this organization.", "required": true } ], "tags": [ "User / team / organization / usage" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedOrganizationPatchPayload" } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/organizations/{uid_organization}/asset_usage/": { "get": { "operationId": "api_v2_organizations_asset_usage_list", "description": "## Retrieve organization asset usage tracker\n\nTracks the total usage of each asset for the user in the given organization\n\nUse the `q` query parameter to filter by project name (e.g. `?q=household survey`). Bare search terms must be at least 3 characters long and match anywhere in the name, case-insensitively. The standard query syntax is also supported: `?q=name__icontains:household` for a contains match, while `?q=name:Household survey` is an exact name match.\n", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Paginate results with limit parameter" }, { "in": "query", "name": "ordering", "schema": { "type": "string" }, "description": "Which field to use when ordering the results." }, { "in": "query", "name": "q", "schema": { "type": "string" }, "description": "Filter the results with search query" }, { "in": "query", "name": "start", "schema": { "type": "integer" }, "description": "Paginate results with start parameter" }, { "in": "path", "name": "uid_organization", "schema": { "type": "string" }, "description": "A unique value identifying this organization.", "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCustomAssetUsageList" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/organizations/{uid_organization}/assets/": { "get": { "operationId": "api_v2_organizations_assets_retrieve", "description": "## Retrieve Organization Assets\n\nThis endpoint returns all assets associated with a specific organization.\nThe assets listed here are restricted to those owned by the specified\norganization.\n\nOnly the owner or administrators of the organization can access this endpoint.\n\n### Additional Information\nFor more details, please refer to `/api/v2/assets/`.\n", "parameters": [ { "in": "path", "name": "uid_organization", "schema": { "type": "string" }, "description": "A unique value identifying this organization.", "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAssetList" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/organizations/{uid_organization}/assets/counts/": { "get": { "operationId": "api_v2_organizations_assets_counts_retrieve", "description": "## Return counts of deployed, archived, and draft assets owned by the organization\n", "parameters": [ { "in": "path", "name": "uid_organization", "schema": { "type": "string" }, "description": "A unique value identifying this organization.", "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetListCount" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/organizations/{uid_organization}/assets/minimal-list/": { "get": { "operationId": "api_v2_organizations_assets_minimal_list_retrieve", "description": "## Return a minimal listing of assets in an organization\n\nReturns a paginated list of assets owned by the organization, including only `uid`, `name`, and `deployment_status` (`draft`, `deployed`, or `archived`).\n\nUse the `q` query parameter to filter by asset type (e.g. `?q=asset_type:survey`).\n\nResponses do not include a `count` field. Use the `next` and `previous` links to paginate through results.\n", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Number of results to return per page." }, { "in": "query", "name": "q", "schema": { "type": "string" }, "description": "Filter the results with search query" }, { "in": "query", "name": "start", "schema": { "type": "integer" }, "description": "The initial index from which to return the results." }, { "in": "path", "name": "uid_organization", "schema": { "type": "string" }, "description": "A unique value identifying this organization.", "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAssetMinimalListList" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/organizations/{uid_organization}/invites/": { "get": { "operationId": "api_v2_organizations_invites_list", "description": "## List organization invites\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } }, { "in": "path", "name": "uid_organization", "schema": { "type": "string" }, "description": "UID of the organization asset", "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedInviteResponseList" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "post": { "operationId": "api_v2_organizations_invites_create", "description": "## Create Organization Invite\n\n* Create organization invites for registered and unregistered users.\n* Set the role for which the user is being invited -\n(Choices: `member`, `admin`). Default is `member`.\n", "parameters": [ { "in": "path", "name": "uid_organization", "schema": { "type": "string" }, "description": "UID of the organization asset", "required": true } ], "tags": [ "User / team / organization / usage" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteCreatePayload" } } }, "required": true }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteCreateResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/organizations/{uid_organization}/invites/{guid}/": { "get": { "operationId": "api_v2_organizations_invites_retrieve", "description": "## Retrieve organization invite\n", "parameters": [ { "in": "path", "name": "guid", "schema": { "type": "string" }, "description": "GUID of the invite", "required": true }, { "in": "path", "name": "uid_organization", "schema": { "type": "string" }, "description": "UID of the organization asset", "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "patch": { "operationId": "api_v2_organizations_invites_partial_update", "description": "## Update Organization Invite\n\n* Update an organization invite to accept, decline, cancel, expire, or resend.\n* Update the role of the invitee to `admin` or `member`. Only the owner or admin can update the role.\n\n", "parameters": [ { "in": "path", "name": "guid", "schema": { "type": "string" }, "description": "GUID of the invite", "required": true }, { "in": "path", "name": "uid_organization", "schema": { "type": "string" }, "description": "UID of the organization asset", "required": true } ], "tags": [ "User / team / organization / usage" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedInvitePatchPayload" }, "examples": { "UpdatingStatus": { "value": { "status": "string" }, "summary": "Updating status" }, "UpdatingRole": { "value": { "role": "string" }, "summary": "Updating role" } } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } }, "delete": { "operationId": "api_v2_organizations_invites_destroy", "description": "## Delete Organization Invite\n\n* Organization owner or admin can delete an organization invite.\n", "parameters": [ { "in": "path", "name": "guid", "schema": { "type": "string" }, "description": "GUID of the invite", "required": true }, { "in": "path", "name": "uid_organization", "schema": { "type": "string" }, "description": "UID of the organization asset", "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "204": { "description": "No response body" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/organizations/{uid_organization}/members/": { "get": { "operationId": "api_v2_organizations_members_list", "description": "## List Members\n\nRetrieves all members and pending invitations in the specified organization.\n\n### Searching\n\nSearch can be made with the `q` parameter. It will implicitly match against the username, email, first name, last name, and profile name (`extra_details__data__name`) of the members or pending invitations.\n\n```shell\ncurl -X GET https://kf.kobotoolbox.org/api/v2/organizations/{uid_organization}/members/?q=luis\n```\n\n> [!WARNING]\n> **Explicit Field Searching:** Because this endpoint combines active members (`OrganizationUser`) and pending invitations (`OrganizationInvitation`), you cannot use an explicit boolean `OR` across different model fields in the same query (e.g., `q=user__email:luis@example.com OR invitee__email:luis@example.com`). Doing so will cause both query parsers to reject the invalid field, resulting in a 400 Bad Request error.\n> \n> To search across both groups simultaneously, simply rely on the generic query (e.g., `q=luis@example.com`) without specifying prefixes. Use explicit field prefixes ONLY when you want to narrow the results to a specific group (e.g., `q=user__email:luis@example.com` to target only active members).\n\n### Sorting\n\nResults can be sorted with the `ordering` parameter, e.g.:\n\n```shell\ncurl -X GET https://kf.kobotoolbox.org/api/v2/organizations/{uid_organization}/members/?ordering=-user__username\n```\n\nAllowed ordering fields:\n\n- `user__username`\n- `status`\n- `date_joined` (or `date_added`, `created`)\n- `role` (sorted by privilege rank: `member` → `admin` → `owner`)\n- `user__has_sso_enabled`\n\nPrefix field names with `-` for descending sort.\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "in": "query", "name": "ordering", "schema": { "type": "string", "enum": [ "-created", "-date_added", "-date_joined", "-role", "-status", "-user__has_sso_enabled", "-user__username", "created", "date_added", "date_joined", "role", "status", "user__has_sso_enabled", "user__username" ] }, "description": "Which field to use when ordering the results. Note: `role` sorts by privilege rank (`member` → `admin` → `owner`)." }, { "in": "query", "name": "q", "schema": { "type": "string" }, "description": "Filter the results with a search query." }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } }, { "in": "path", "name": "uid_organization", "schema": { "type": "string" }, "description": "UID of the organization", "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedMemberListResponseList" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/organizations/{uid_organization}/members/{username}/": { "get": { "operationId": "api_v2_organizations_members_retrieve", "description": "## Retrieve Member Details\n\nRetrieves the details of a specific member within an organization by username.\n", "parameters": [ { "in": "path", "name": "uid_organization", "schema": { "type": "string" }, "description": "UID of the organization", "required": true }, { "in": "path", "name": "username", "schema": { "type": "string" }, "description": "Username of the user", "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberListResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "patch": { "operationId": "api_v2_organizations_members_partial_update", "description": "## Update Member Role\n\nUpdates the role of a member within the organization to `admin` or\n`member`.\n\n- **admin**: Grants the member admin privileges within the organization\n- **member**: Revokes admin privileges, setting the member as a regular user\n", "parameters": [ { "in": "path", "name": "uid_organization", "schema": { "type": "string" }, "description": "UID of the organization", "required": true }, { "in": "path", "name": "username", "schema": { "type": "string" }, "description": "Username of the user", "required": true } ], "tags": [ "User / team / organization / usage" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedMemberPatchRequest" } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberListResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } }, "delete": { "operationId": "api_v2_organizations_members_destroy", "description": "## Remove Member\n\nDelete an organization member.\n", "parameters": [ { "in": "path", "name": "uid_organization", "schema": { "type": "string" }, "description": "UID of the organization", "required": true }, { "in": "path", "name": "username", "schema": { "type": "string" }, "description": "Username of the user", "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "204": { "description": "No response body" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/organizations/{uid_organization}/service_usage/": { "get": { "operationId": "api_v2_organizations_service_usage_retrieve", "description": "## Organization Usage Tracker\n\n- Tracks the total usage of different services for each account in an organization\n- Tracks the submissions and NLP seconds/characters for the current month/year/all time\n- Tracks the current total storage used\n- Includes a detailed list of balances relative to a user's usage limits\n- If no organization is found with the provided ID, returns the usage for the logged-in user\n\n**This endpoint is cached for an amount of time determined by ENDPOINT_CACHE_DURATION**\n", "parameters": [ { "in": "path", "name": "uid_organization", "schema": { "type": "string" }, "description": "A unique value identifying this organization.", "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationServiceUsageResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/permissions/": { "get": { "operationId": "api_v2_permissions_list", "description": "## List all assignable permissions for `Asset`\n\nThe `implied` property of a given permission shows which additional\npermissions are automatically granted when assigning that particular\npermission.\n\nThe `contradictory` property shows which permissions are removed when\nassigning that particular permission.\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "Other" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, {} ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedPermissionResponseList" } } }, "description": null } } } }, "/api/v2/permissions/{codename}/": { "get": { "operationId": "api_v2_permissions_retrieve", "description": "## Retrieve a codename's permissions\n", "parameters": [ { "in": "path", "name": "codename", "schema": { "type": "string" }, "required": true } ], "tags": [ "Other" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, {} ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionResponse" } } }, "description": null } } } }, "/api/v2/project-history-logs/": { "get": { "operationId": "api_v2_project_history_logs_list", "description": "## List all project history logs for all projects.\n\n⚠️_Only available to superusers_\n\nResults from this endpoint can be filtered by a Boolean query\nspecified in the `q` parameter.\n\n**Filterable fields for all project history logs:**\n\n* date_created\n* user_uid\n* user__username\n* user__email\n* user__is_superuser\n* metadata__source\n* metadata__ip_address\n* metadata__asset_uid\n* metadata__log_subtype\n * available subtypes: \"project\", \"permission\"\n* action\n\navailable actions:\n\n> add-media\n> add-submission\n> allow-anonymous-submissions\n> archive\n> clone-permissions\n> connect-project\n> delete-media\n> delete-service\n> delete-submission\n> deploy\n> disable-sharing\n> disallow-anonymous-submissions\n> disconnect-project\n> enable-sharing\n> export\n> modify-imported-fields\n> modify-qa-data\n> modify-service\n> modify-sharing\n> modify-submission\n> modify-user-permissions\n> redeploy\n> register-service\n> replace-form\n> share-data-publicly\n> share-form-publicly\n> transfer\n> unarchive\n> unshare-data-publicly\n> unshare-form-publicly\n> update-content\n> update-name\n> update-settings\n> update-qa\n> view-data\n\n**Filterable fields by action:**\n\n* add-media\n\n a. metadata__asset-file__uid\n\n b. metadata__asset-file__filename\n\n* add-submission\n\n a. metadata__submission__submitted_by\n\n b. metadata__submission__root_uuid\n\n* archive\n\n a. metadata__latest_version_uid\n\n* clone-permissions\n\n a. metadata__cloned_from\n\n* connect-project\n\n a. metadata__paired-data__source_uid\n\n b. metadata__paired-data__source_name\n\n* delete-media\n\n a. metadata__asset-file__uid\n\n b. metadata__asset-file__filename\n\n* delete-service\n\n a. metadata__hook__uid\n\n b. metadata__hook__endpoint\n\n c. metadata__hook__active\n\n* delete-submission\n\n a. metadata__submission__submitted_by\n\n b. metadata__submission__root_uuid\n\n* deploy\n\n a. metadata__latest_version_uid\n\n b. metadata__latest_deployed_version_uid\n\n* disconnect-project\n\n a. metadata__paired-data__source_uid\n\n b. metadata__paired-data__source_name\n\n* modify-imported-fields\n\n a. metadata__paired-data__source_uid\n\n b. metadata__paired-data__source_name\n\n* modify-qa-data\n\n a. metadata__submission__submitted_by\n\n b. metadata__submission__root_uuid\n\n* modify-service\n\n a. metadata__hook__uid\n\n b. metadata__hook__endpoint\n\n c. metadata__hook__active\n\n* modify-submission\n\n a. metadata__submission__submitted_by\n\n b. metadata__submission__root_uuid\n\n b. metadata__submission__status (only present if changed)\n\n* modify-user-permissions\n\n a. metadata__permissions__username\n\n* redeploy\n\n a. metadata__latest_version_uid\n\n b. metadata__latest_deployed_version_uid\n\n* register-service\n\n a. metadata__hook__uid\n\n b. metadata__hook__endpoint\n\n c. metadata__hook__active\n\n* transfer\n\n a. metadata__username\n\n* unarchive\n\n a. metadata__latest_version_uid\n\n* update-name\n\n a. metadata__name__old\n\n b. metadata__name__new\n\n* update-settings\n\n a. metadata__settings__description__old\n\n b. metadata__settings__description__new\n\nThis endpoint can be paginated with 'start' and 'limit' parameters\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "in": "query", "name": "q", "schema": { "type": "string" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "Server logs (superusers)" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedProjectHistoryLogResponseList" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/project-history-logs/export/": { "get": { "operationId": "api_v2_project_history_logs_export_retrieve", "description": "## List of Project History Exports\n\n⚠️ _Only available to superusers_\n", "tags": [ "Server logs (superusers)" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportHistoryResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "post": { "operationId": "api_v2_project_history_logs_export_create", "description": "## Create an export of projects history logs\n\n⚠️ _Only available to superusers_\n\nExport project history logs and send it by email to the requesting user.\n", "tags": [ "Server logs (superusers)" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportHistoryResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/project-ownership/invites/": { "get": { "operationId": "api_v2_project_ownership_invites_list", "description": "## List of invites\n\nInvites sent or received by current user about transferring project ownership.\n\nList can be filtered with `mode` parameter, e.g.: display only received invites.\n\nPossible values for `mode`:\n- `sender`\n- `recipient`\n\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "in": "query", "name": "mode", "schema": { "type": "string" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "Manage projects and library content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedProjectInviteResponseList" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" } } }, "post": { "operationId": "api_v2_project_ownership_invites_create", "description": "## Create (send) an invite\n\nWhere the assets `uid` are given in the payload's list\n\n\n", "tags": [ "Manage projects and library content" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectInviteCreatePayload" } } }, "required": true }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectInviteResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/project-ownership/invites/{uid_invite}/": { "get": { "operationId": "api_v2_project_ownership_invites_retrieve", "description": "## Invite detail\n\nIt can be useful to monitor the invite status while the transfer is being processed\n", "parameters": [ { "in": "path", "name": "uid_invite", "schema": { "type": "string" }, "required": true } ], "tags": [ "Manage projects and library content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectInviteResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "patch": { "operationId": "api_v2_project_ownership_invites_partial_update", "description": "## Update an invite status\n\nUpdate the status of an invite.\nStatus accepted:\n- `cancelled`\n- `accepted`\n- `declined`\n\n**Notes**:\n- _When submitting `accepted` the invite status becomes automatically `in_progress`_\n- _Only the sender can cancel an invite, and **if only if** the invite is still pending._\n- _Only the recipient can accept or decline, **if and only if** the invite is still pending._\n\n", "parameters": [ { "in": "path", "name": "uid_invite", "schema": { "type": "string" }, "required": true } ], "tags": [ "Manage projects and library content" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedInviteUpdatePayload" } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectInviteResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } }, "delete": { "operationId": "api_v2_project_ownership_invites_destroy", "description": "## Delete invite\n", "parameters": [ { "in": "path", "name": "uid_invite", "schema": { "type": "string" }, "required": true } ], "tags": [ "Manage projects and library content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "204": { "description": "No response body" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/project-ownership/invites/{uid_invite}/transfers/{uid_transfer}/": { "get": { "operationId": "api_v2_project_ownership_invites_transfers_retrieve", "description": "## Retrieve transfer details\n", "parameters": [ { "in": "path", "name": "uid_invite", "schema": { "type": "string" }, "description": "UID of the parent invite", "required": true }, { "in": "path", "name": "uid_transfer", "schema": { "type": "string" }, "required": true } ], "tags": [ "Manage projects and library content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferListResponse" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/project-views/": { "get": { "operationId": "api_v2_project_views_list", "description": "## List project views for current user\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedProjectViewListResponseList" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" } } } }, "/api/v2/project-views/{uid_project_view}/": { "get": { "operationId": "api_v2_project_views_retrieve", "description": "## Retrieve project view of a shared project to current user\n", "parameters": [ { "in": "path", "name": "uid_project_view", "schema": { "type": "string" }, "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectViewListResponse" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/project-views/{uid_project_view}/{obj_type}/export/": { "get": { "operationId": "api_v2_project_views_export_retrieve", "description": "## Retrieve an export for the requested object\n\n* Note: `{obj_type}` can either be `users` or `assets`\n\n", "parameters": [ { "in": "path", "name": "obj_type", "schema": { "type": "string", "pattern": "^(assets|users)$" }, "required": true }, { "in": "path", "name": "uid_project_view", "schema": { "type": "string" }, "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectViewExportResponse" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } }, "post": { "operationId": "api_v2_project_views_export_create", "description": "## Create an export for the requested object\n\n* Note: `{obj_type}` can either be `users` or `assets`\n", "parameters": [ { "in": "path", "name": "obj_type", "schema": { "type": "string", "pattern": "^(assets|users)$" }, "required": true }, { "in": "path", "name": "uid_project_view", "schema": { "type": "string" }, "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectViewExportCreateResponse" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/project-views/{uid_project_view}/assets/": { "get": { "operationId": "api_v2_project_views_assets_retrieve", "description": "## Retrieve assets available in project view\n", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Paginate results with limit parameter" }, { "in": "query", "name": "start", "schema": { "type": "integer" }, "description": "Paginate results with start parameter" }, { "in": "path", "name": "uid_project_view", "schema": { "type": "string" }, "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedProjectViewAssetResponseList" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/project-views/{uid_project_view}/assets/counts/": { "get": { "operationId": "api_v2_project_views_assets_counts_retrieve", "description": "## Return counts of deployed, archived, and draft assets in the project view\n", "parameters": [ { "in": "path", "name": "uid_project_view", "schema": { "type": "string" }, "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetListCount" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/project-views/{uid_project_view}/assets/minimal-list/": { "get": { "operationId": "api_v2_project_views_assets_minimal_list_retrieve", "description": "## Return a minimal listing of assets in a project view\n\nReturns a paginated list of assets visible within the project view, including only `uid`, `name`, and `deployment_status` (`draft`, `deployed`, or `archived`).\n\nUse the `q` query parameter to filter by asset type (e.g. `?q=asset_type:survey`).\n\nResponses do not include a `count` field. Use the `next` and `previous` links to paginate through results.\n", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Number of results to return per page." }, { "in": "query", "name": "q", "schema": { "type": "string" }, "description": "Filter the results with search query" }, { "in": "query", "name": "start", "schema": { "type": "integer" }, "description": "The initial index from which to return the results." }, { "in": "path", "name": "uid_project_view", "schema": { "type": "string" }, "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAssetMinimalListList" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/project-views/{uid_project_view}/users/": { "get": { "operationId": "api_v2_project_views_users_retrieve", "description": "## Retrieve users available in project view\n", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Paginate results with limit parameter" }, { "in": "query", "name": "start", "schema": { "type": "integer" }, "description": "Paginate results with start parameter" }, { "in": "path", "name": "uid_project_view", "schema": { "type": "string" }, "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedProjectViewUserResponseList" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/scim/v2/{idp_slug}/Groups": { "get": { "operationId": "api_v2_scim_v2_Groups_list", "description": "Returns a list of SCIM groups.", "parameters": [ { "name": "count", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "in": "path", "name": "idp_slug", "schema": { "type": "string" }, "required": true }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "startIndex", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "SCIM" ], "security": [ { "ScimAuth": [] } ], "responses": { "401": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "403": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "200": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/PaginatedScimGroupList" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedScimGroupList" } } }, "description": "" } } }, "post": { "operationId": "api_v2_scim_v2_Groups_create", "description": "Creates a new SCIM group.", "parameters": [ { "in": "path", "name": "idp_slug", "schema": { "type": "string" }, "required": true } ], "tags": [ "SCIM" ], "requestBody": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } }, "required": true }, "security": [ { "ScimAuth": [] } ], "responses": { "401": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "403": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "201": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } }, "description": "" } } } }, "/api/v2/scim/v2/{idp_slug}/Groups/{id}": { "get": { "operationId": "api_v2_scim_v2_Groups_retrieve", "description": "Returns a specific SCIM group.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "A unique value identifying this SCIM Group.", "required": true }, { "in": "path", "name": "idp_slug", "schema": { "type": "string" }, "required": true } ], "tags": [ "SCIM" ], "security": [ { "ScimAuth": [] } ], "responses": { "401": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "403": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "200": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } }, "description": "" } } }, "put": { "operationId": "api_v2_scim_v2_Groups_update", "description": "Replaces a SCIM group entirely.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "A unique value identifying this SCIM Group.", "required": true }, { "in": "path", "name": "idp_slug", "schema": { "type": "string" }, "required": true } ], "tags": [ "SCIM" ], "requestBody": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } }, "required": true }, "security": [ { "ScimAuth": [] } ], "responses": { "401": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "403": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "200": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } }, "description": "" } } }, "patch": { "operationId": "api_v2_scim_v2_Groups_partial_update", "description": "Updates a SCIM group. Supports adding/removing members via patch operations.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "A unique value identifying this SCIM Group.", "required": true }, { "in": "path", "name": "idp_slug", "schema": { "type": "string" }, "required": true } ], "tags": [ "SCIM" ], "requestBody": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/PatchedScimGroup" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PatchedScimGroup" } } } }, "security": [ { "ScimAuth": [] } ], "responses": { "401": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "403": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "200": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimGroup" } } }, "description": "" } } }, "delete": { "operationId": "api_v2_scim_v2_Groups_destroy", "description": "Deletes a SCIM group.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "A unique value identifying this SCIM Group.", "required": true }, { "in": "path", "name": "idp_slug", "schema": { "type": "string" }, "required": true } ], "tags": [ "SCIM" ], "security": [ { "ScimAuth": [] } ], "responses": { "401": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "403": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "204": { "description": "No response body" } } } }, "/api/v2/scim/v2/{idp_slug}/ResourceTypes": { "get": { "operationId": "api_v2_scim_v2_ResourceTypes_retrieve", "description": "Returns the SCIM supported ResourceTypes.", "parameters": [ { "in": "path", "name": "idp_slug", "schema": { "type": "string" }, "required": true } ], "tags": [ "SCIM" ], "security": [ { "ScimAuth": [] } ], "responses": { "401": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "403": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "200": { "content": { "application/scim+json": { "schema": { "type": "object", "additionalProperties": {} } } }, "description": "" } } } }, "/api/v2/scim/v2/{idp_slug}/Schemas": { "get": { "operationId": "api_v2_scim_v2_Schemas_retrieve", "description": "Returns the SCIM supported Schemas.", "parameters": [ { "in": "path", "name": "idp_slug", "schema": { "type": "string" }, "required": true } ], "tags": [ "SCIM" ], "security": [ { "ScimAuth": [] } ], "responses": { "401": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "403": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "200": { "content": { "application/scim+json": { "schema": { "type": "object", "additionalProperties": {} } } }, "description": "" } } } }, "/api/v2/scim/v2/{idp_slug}/ServiceProviderConfig": { "get": { "operationId": "api_v2_scim_v2_ServiceProviderConfig_retrieve", "description": "Returns the SCIM Service Provider Configuration.", "parameters": [ { "in": "path", "name": "idp_slug", "schema": { "type": "string" }, "required": true } ], "tags": [ "SCIM" ], "security": [ { "ScimAuth": [] } ], "responses": { "401": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "403": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "200": { "content": { "application/scim+json": { "schema": { "type": "object", "additionalProperties": {} } } }, "description": "" } } } }, "/api/v2/scim/v2/{idp_slug}/Users": { "get": { "operationId": "api_v2_scim_v2_Users_list", "description": "Returns a list of SCIM users matching the optional query", "parameters": [ { "name": "count", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "in": "path", "name": "idp_slug", "schema": { "type": "string" }, "required": true }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "startIndex", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "SCIM" ], "security": [ { "ScimAuth": [] } ], "responses": { "401": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "403": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "200": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/PaginatedScimUserList" } } }, "description": "" } } }, "post": { "operationId": "api_v2_scim_v2_Users_create", "description": "Handle POST requests (user provisioning from IdP).", "parameters": [ { "in": "path", "name": "idp_slug", "schema": { "type": "string" }, "required": true } ], "tags": [ "SCIM" ], "requestBody": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimUser" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } }, "required": true }, "security": [ { "ScimAuth": [] } ], "responses": { "401": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "403": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "201": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } }, "description": "" }, "409": { "content": { "application/scim+json": { "schema": { "type": "object", "additionalProperties": {} } } }, "description": "" }, "400": { "content": { "application/scim+json": { "schema": { "type": "object", "additionalProperties": {} } } }, "description": "" } } } }, "/api/v2/scim/v2/{idp_slug}/Users/{id}": { "get": { "operationId": "api_v2_scim_v2_Users_retrieve", "description": "Returns a specific SCIM user.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this user.", "required": true }, { "in": "path", "name": "idp_slug", "schema": { "type": "string" }, "required": true } ], "tags": [ "SCIM" ], "security": [ { "ScimAuth": [] } ], "responses": { "401": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "403": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "200": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } }, "description": "" } } }, "put": { "operationId": "api_v2_scim_v2_Users_update", "description": "Handle PUT requests (user update from IdP).\nAuthentik can send a PUT request to update a user's details. If it tries to\nupdate a user to have a username or email that already exists on another\naccount, we intercept the IntegrityError and return a SCIM 409 Conflict.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this user.", "required": true }, { "in": "path", "name": "idp_slug", "schema": { "type": "string" }, "required": true } ], "tags": [ "SCIM" ], "requestBody": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimUser" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } }, "required": true }, "security": [ { "ScimAuth": [] } ], "responses": { "401": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "403": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "200": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } }, "description": "" }, "409": { "content": { "application/scim+json": { "schema": { "type": "object", "additionalProperties": {} } } }, "description": "" } } }, "patch": { "operationId": "api_v2_scim_v2_Users_partial_update", "description": "Updates a SCIM user. Currently only supports deactivation via the `active` attribute.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this user.", "required": true }, { "in": "path", "name": "idp_slug", "schema": { "type": "string" }, "required": true } ], "tags": [ "SCIM" ], "requestBody": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/PatchedScimUser" } }, "application/json": { "schema": { "$ref": "#/components/schemas/PatchedScimUser" } } } }, "security": [ { "ScimAuth": [] } ], "responses": { "401": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "403": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "200": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimUser" } } }, "description": "" } } }, "delete": { "operationId": "api_v2_scim_v2_Users_destroy", "description": "Deactivates all Kobo accounts linked to the user's email address.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "integer" }, "description": "A unique integer value identifying this user.", "required": true }, { "in": "path", "name": "idp_slug", "schema": { "type": "string" }, "required": true } ], "tags": [ "SCIM" ], "security": [ { "ScimAuth": [] } ], "responses": { "401": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "403": { "content": { "application/scim+json": { "schema": { "$ref": "#/components/schemas/ScimError" } } }, "description": "" }, "204": { "description": "No response body" } } } }, "/api/v2/service_usage/": { "get": { "operationId": "api_v2_service_usage_list", "description": "⚠️ Deprecated\n## Track Service Usage\n\nTracks the total usage of different services for the logged-in user.
\nTracks the submissions and NLP seconds/characters for the current month/year/all time.
\nTracks the current total storage used.
\nNote: this endpoint is not currently used by the frontend to display usage information.
\nSee `/api/v2/organizations/{organization_id}/service_usage/` for the endpoint we use on the Usage page.
\n", "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceUsageResponse" } } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" } } } }, "/api/v2/social-apps/{provider_id}/": { "get": { "operationId": "api_v2_social_apps_retrieve", "description": "## Retrieve a single sign-on provider\n\nResolves the `provider_id` used in single sign-on URLs into the provider's display\nname, so a client can render the \"Log in with …\" screen and tell a real provider\nfrom a typo.\n\nReturns display data only, never `client_id`, secrets, or the provider's server URL.\n\nExamples:\n```shell\n curl -X GET https://kf.kobotoolbox.org/api/v2/social-apps/nca/\n```\n\n> Response 200\n```json\n{\n \"provider_id\": \"nca\",\n \"name\": \"Norwegian Church Aid\"\n}\n```\n\nRequires no authentication, and resolves providers that are hidden from the login\npage as well as those shown on it: a hidden provider is not advertised, but is\nusable by anyone holding its link, and that link already contains the\n`provider_id`. There is intentionally no endpoint listing all providers, the\n`social_apps` property of `/api/v2/environment/` lists the public ones only.\n\nAn unknown `provider_id` returns `404`.\n", "parameters": [ { "in": "path", "name": "provider_id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Configuration" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, {} ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialAppDetail" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/stripe/addons/": { "get": { "operationId": "api_v2_stripe_addons_list", "description": "Lists the one-time add-ons for the authenticated user's organization.", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "Other" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOneTimeAddOnList" } } }, "description": "" } } } }, "/api/v2/stripe/addons/{id}/": { "get": { "operationId": "api_v2_stripe_addons_retrieve", "description": "Lists the one-time add-ons for the authenticated user's organization.", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "description": "A unique value identifying this plan add-on.", "required": true } ], "tags": [ "Other" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OneTimeAddOn" } } }, "description": "" } } } }, "/api/v2/stripe/change-plan": { "get": { "operationId": "api_v2_stripe_change_plan_retrieve", "description": "Change an existing subscription to a new price.\n\nThis will immediately change their subscription to the new plan if upgrading, prorating the charge.\nIf the user is downgrading to a lower price, it will schedule the change at the end of the current billing period.\n\n
\nGET /api/v2/stripe/change-plan/?subscription_id={subscription_id}&price_id={price_id}\n
\n\n> Example\n>\n> curl -X GET https://[kpi]/api/v2/stripe/change-plan/\n\n> **Payload**\n>\n> {\n> \"price_id\": \"price_A34cds8fmske3tf\",\n> \"subscription_id\": \"sub_s9aNFrd2fsmld4gz\",\n> \"quantity\": 100000\n> }\n\nwhere:\n\n* \"price_id\" (required) is the Stripe Price ID for the plan the user is changing to.\n* \"quantity\" is the quantity for the new subscription price (default: 1).\n* \"subscription_id\" (required) is a Stripe Subscription ID for the subscription being changed.", "tags": [ "Other" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePlan" } } }, "description": "" } } } }, "/api/v2/stripe/checkout-link": { "post": { "operationId": "api_v2_stripe_checkout_link_create", "tags": [ "Other" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutLink" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CheckoutLink" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CheckoutLink" } } }, "required": true }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutLink" } } }, "description": "" } } } }, "/api/v2/stripe/customer-portal": { "post": { "operationId": "api_v2_stripe_customer_portal_create", "tags": [ "Other" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPortal" } } }, "required": true }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPortalPostResponse" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/stripe/products/": { "get": { "operationId": "api_v2_stripe_products_list", "description": "Returns Product and Price Lists, sorted from the product with the lowest price to highest\nThis endpoint is cached for an amount of time determined by ENDPOINT_CACHE_DURATION\n\n
\nGET /api/v2/stripe/products/\n
\n\n> Example\n>\n> curl -X GET https://[kpi]/api/v2/stripe/products/\n\n> Response\n>\n> HTTP 200 Ok\n> {\n> \"count\": ...\n> \"next\": ...\n> \"previous\": ...\n> \"results\": [\n> {\n> \"id\": string,\n> \"name\": string,\n> \"type\": string,\n> \"prices\": [\n> {\n> \"id\": string,\n> \"nickname\": string,\n> \"currency\": string,\n> \"type\": string,\n> \"recurring\": {\n> \"aggregate_usage\": string ('sum', 'last_during_period`, `last_ever`, `max`)\n> \"interval\": string ('month', 'year', 'week', 'day')\n> \"interval_count\": int,\n> \"usage_type\": string ('metered', 'licensed')\n> },\n> \"unit_amount\": int (cents),\n> \"human_readable_price\": string,\n> \"metadata\": {},\n> \"active\": bool,\n> \"product\": string,\n> \"transform_quantity\": null | {'round': 'up'|'down', 'divide_by': int}\n> },\n> ...\n> ],\n> \"metadata\": {},\n> },\n> ...\n> ]\n> }\n>\n\n### Note: unit_amount is price in cents (assuming currency is USD/AUD/CAD/etc.)\n\n## Current Endpoint", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "Other" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, {} ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedProductList" } } }, "description": "" } } } }, "/api/v2/stripe/subscriptions/": { "get": { "operationId": "api_v2_stripe_subscriptions_list", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "Other" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSubscriptionList" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" } } } }, "/api/v2/stripe/subscriptions/{id}/": { "get": { "operationId": "api_v2_stripe_subscriptions_retrieve", "parameters": [ { "in": "path", "name": "id", "schema": { "type": "string" }, "required": true } ], "tags": [ "Other" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } }, "description": "" } } } }, "/api/v2/tags/": { "get": { "operationId": "api_v2_tags_list", "description": "## List current user's assets' tags\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "Manage projects and library content" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] }, {} ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTagListResponseList" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" } } } }, "/api/v2/terms-of-service/": { "get": { "operationId": "api_v2_terms_of_service_list", "description": "## List the different terms of service\n", "tags": [ "Other" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TermsOfServiceResponse" } } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" } } } }, "/api/v2/terms-of-service/{slug}/": { "get": { "operationId": "api_v2_terms_of_service_retrieve", "description": "## Retrieve a specific terms of service\n", "parameters": [ { "in": "path", "name": "slug", "schema": { "type": "string" }, "required": true } ], "tags": [ "Other" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsOfServiceResponse" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/transcription-services/": { "get": { "operationId": "api_v2_transcription_services_list", "description": "## List the transcription services accessible to requesting user.\n\nSearch can be made with `q` parameter to search for the term in names and codes.\n\nResults are order by name.\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "in": "query", "name": "q", "schema": { "type": "string" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "Other" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTranscriptionServiceList" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" } } } }, "/api/v2/transcription-services/{code}/": { "get": { "operationId": "api_v2_transcription_services_retrieve", "description": "## retrieve a transcription service\n\n* `code` - is the unique identifier of a specific language\n", "parameters": [ { "in": "path", "name": "code", "schema": { "type": "string" }, "required": true } ], "tags": [ "Other" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranscriptionService" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/translation-services/": { "get": { "operationId": "api_v2_translation_services_list", "description": "## List the translation services accessible to requesting (authenticated) user.\n\nSearch can be made with `q` parameter to search for the term in names and codes.\n\nResults are ordered by name.\n\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "in": "query", "name": "q", "schema": { "type": "string" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "Other" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTranslationServiceList" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/translation-services/{code}/": { "get": { "operationId": "api_v2_translation_services_retrieve", "description": "## Retrieve a translation service\n\n* `code` - is the unique identifier of a specific language\n", "parameters": [ { "in": "path", "name": "code", "schema": { "type": "string" }, "required": true } ], "tags": [ "Other" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationService" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/user-reports/": { "get": { "operationId": "api_v2_user_reports_list", "description": "# List user reports\n\n⚠️ _Only available to superusers_\n\n## Filterable fields by string:\n\nSupports partial filtering\n- username\n- first_name\n- last_name\n- email\n- user_uid\n- organization__name\n- organization__role (e.g., admin, member, owner)\n- organization__website\n- extra_details__data__organization_type\n- `extra_details__data__` (other string fields, e.g., name, sector, country...)\n\n## Filterable fields by int:\n\nSupports exact matching and range operators (e.g., gte, lte)\n\n**Total NLP Usage**\n- service_usage__total_nlp_usage__asr_seconds_all_time\n- service_usage__total_nlp_usage__mt_characters_all_time\n- service_usage__total_nlp_usage__llm_requests_all_time\n- service_usage__total_nlp_usage__asr_seconds_current_period\n- service_usage__total_nlp_usage__mt_characters_current_period\n- service_usage__total_nlp_usage__llm_requests_current_period\n\n**Total Storage/Submissions**\n- service_usage__total_storage_bytes\n- service_usage__total_submission_count__cumulative\n- service_usage__total_submission_count__current_period\n\n**Service Usage Balances**\n\nPrefix: `service_usage__balances____`\n\nMetric:\n- submission\n- asr_seconds\n- mt_characters\n- storage_bytes\n- llm_requests\n\nValue:\n- balance_value\n- balance_percent\n- effective_limit\n\nEx: `service_usage__balances__submission__balance_value`\n\n**Asset Count**\n- asset_count\n- active_project_count\n\n## Filterable fields by date:\nSupports exact matching and range operators (e.g., gte, lte)\n\n- date_joined\n- last_login\n- last_updated (Represents the last modified timestamp of the materialized view)\n- extra_details__date_removal_requested\n- extra_details__date_removed\n- extra_details_password_date_changed\n\n## Filterable fields by boolean:\n\n- is_superuser\n- is_staff\n- is_active\n- validated_email\n- extra_details__validated_password\n- mfa_is_active\n- sso_is_active\n- accepted_tos\n- extra_details__data__newsletter_subscription\n- service_usage__balances__*metric*__exceeded (metric: submission, asr_seconds, mt_characters, storage_bytes, llm_requests)\n- account_restricted\n\n## Filterable fields by list:\n\nSubscription filtering:\n\nHas subscriptions\n\n`?q=subscriptions__0__id__isnull:False`\n\nNo subscriptions\n\n`?q=subscriptions__0__id__isnull:True`\n\nSubscription id\n\n`?q=subscriptions[]__id:sub_1QwPItAR39rDI89stzLJ040p`\n\nActive subscriptions\n\n`?q=subscriptions[]__status:active`\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "ordering", "required": false, "in": "query", "description": "Which field to use when ordering the results.", "schema": { "type": "string" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "Server logs (superusers)" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedUserReportsListResponseList" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/api/v2/users/": { "get": { "operationId": "api_v2_users_list", "description": "## List users\n\n⚠️ _Only available to superusers_\n\nSearch can be made with `q` parameter.\n\nAllowed fields are:\n\n- `username`\n- `is_active`\n- `email`\n- `date_joined`\n- `last_login`\n- `extra_details__data__`\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedUserListResponseList" } } }, "description": null }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" } } } }, "/api/v2/users/{username}/": { "get": { "operationId": "api_v2_users_retrieve", "description": "## Retrieve a user\n\n⚠️ _Regular users have access to active users only_\n", "parameters": [ { "in": "path", "name": "username", "schema": { "type": "string", "description": "Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only." }, "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserRetrieveResponse" } } }, "description": null }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/me/": { "get": { "operationId": "me_retrieve", "description": "## Retrieve current user profile\n", "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeListResponse" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" } } }, "patch": { "operationId": "me_partial_update", "description": "## Update current user infos\n", "tags": [ "User / team / organization / usage" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchedCurrentUser" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/PatchedCurrentUser" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/PatchedCurrentUser" } } } }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeListResponse" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } }, "delete": { "operationId": "me_destroy", "description": "## Delete current user\n\n> Payload Example:\n>\n> {\n> \"confirm\": \"user__extra_details__uid\",\n> }\n\n\n### !! Due to current DRF-Spectacular limitations with AOS 3.1, DELETE operations do not display request or response bodies in this documentation (as payloads are not typically recommended for DELETE). This means direct testing is unavailable. However, example payloads and responses are provided for reference, and HTTP codes/error messages are accurate. !!\n", "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "204": { "description": "No response body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" } } } }, "/me/emails/": { "get": { "operationId": "me_emails_list", "description": "## View current user's email\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedEmailAddressList" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" } } }, "post": { "operationId": "me_emails_create", "description": "## Set a new email\n\nThe new email will be unverified and replace existing unverified, non-primary emails.\nNew email is not usable until verified.\n\n### Re-authentication\n\nChanging the email address is a sensitive action, so a valid session is not enough\non its own: the user must have authenticated recently. \"Recently\" means within\n`ACCOUNT_REAUTHENTICATION_TIMEOUT` (5 minutes by default), and every method the\naccount has available must be fresh, the password, plus MFA when it is enabled.\n\nThis section describes browser sessions. Requests authenticated with a stateless\ncredential (token, Basic or OAuth2) are re-authenticated differently, in the\nrequest body, as described below.\n\nWhen re-authentication is needed the endpoint responds `403` without touching any\nemail address:\n\n```json\n{\n \"detail\": \"Re-authentication is required for this action.\",\n \"code\": \"reauthentication_required\",\n \"flows\": [\n {\"id\": \"reauthenticate\"},\n {\"id\": \"mfa_reauthenticate\", \"types\": [\"totp\"]}\n ]\n}\n```\n\n`code` is the field to branch on: `detail` is translated, so it cannot be\nmatched against reliably.\n\n`flows` lists the steps the client must walk the user through before retrying,\nin the same shape allauth's headless API uses — `reauthenticate` for the\npassword, and `mfa_reauthenticate` in addition when the account has MFA enabled.\nOnce every listed flow is completed the original request will succeed.\n\n### Re-authenticating without a browser session\n\nRequests authenticated with a stateless credential (token, Basic or OAuth2) have\nno session for allauth to record a re-authentication in, so they carry the proof\nin the request body instead:\n\n```json\n{\n \"email\": \"new@example.com\",\n \"current_password\": \"…\",\n \"mfa_code\": \"123456\"\n}\n```\n\n`current_password` is required whenever the account has a usable password.\n`mfa_code` is required in addition when MFA is enabled, and accepts either a TOTP\ncode or a recovery code. Both are rejected with a `400` naming the offending\nfield, and neither is needed for an SSO-only account that has neither.\n\nNote that Basic authentication is refused outright for MFA-enabled accounts, so\nin practice the `mfa_code` case applies to token and OAuth2 callers.\n\nThis endpoint is rate limited.\n\n### Trying this from the API docs\n\nA live KoboToolbox session takes precedence over the token set in **Authorize**:\n`SessionAuthentication` comes first in `DEFAULT_AUTHENTICATION_CLASSES`, so if you\nare logged in, that is what authenticates the call, and the token is never read.\n\n* **To exercise the session payload**, first call\n `POST /api/v2/allauth/browser/v1/auth/reauthenticate` with your password, then\n send `{\"email\": \"…\"}` here within `ACCOUNT_REAUTHENTICATION_TIMEOUT`. Without\n that first call you will get the `403` above.\n* **To exercise the token payloads**, open the docs in a private window so that no\n session cookie is sent, get your token from `/token/`, and authorize with the\n full value including the keyword: `Token `, not the bare key.\n Swagger sends the header verbatim, so omitting the keyword returns `401`.\n", "tags": [ "User / team / organization / usage" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailRequestPayload" }, "examples": { "BrowserSession": { "value": { "email": "new@example.com" }, "summary": "Browser session", "description": "Nothing else is needed: the session already carries the re-authentication, provided it happened within `ACCOUNT_REAUTHENTICATION_TIMEOUT`. If it did not, the response is `403` listing the flows to complete first." }, "TokenOrOAuth2WithoutMFA": { "value": { "email": "new@example.com", "current_password": "" }, "summary": "Token or OAuth2 without MFA", "description": "A stateless credential has no session to re-authenticate in, so the current password proves the request instead. Required whenever the account has a usable password." }, "TokenOrOAuth2WithMFAEnabled": { "value": { "email": "new@example.com", "current_password": "", "mfa_code": "" }, "summary": "Token or OAuth2 with MFA enabled", "description": "Accounts with MFA enabled must also send a code, either from the authenticator app or one of the recovery codes. Note that Basic authentication is refused outright for these accounts, so this applies to token and OAuth2 callers." } } } }, "required": true }, "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAddress" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorValidation" }, "examples": { "BadRequest": { "value": { "field_name": [ "Error message" ] }, "summary": "Bad request" } } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailReauthenticationRequiredResponse" }, "examples": { "Re-authenticationRequired": { "value": { "detail": "Re-authentication is required for this action.", "code": "reauthentication_required", "flows": [ { "id": "reauthenticate" }, { "id": "mfa_reauthenticate", "types": [ "totp" ] } ] }, "summary": "Re-authentication required" } } } }, "description": "The session is valid but the user has not re-authenticated recently enough. Walk the user through every flow listed in `flows`, then retry this request." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 3600 seconds." } } } } }, "description": "Too many email change attempts. The endpoint is rate limited because it accepts `current_password`." } } } }, "/me/social-accounts/": { "get": { "operationId": "me_social_accounts_list", "description": "## List user's social accounts\n", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Number of results to return per page. Use with `start`.", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "Deprecated alias of `start`.", "schema": { "type": "integer" } }, { "name": "start", "required": false, "in": "query", "description": "The initial index from which to return the results. Use with `limit`.", "schema": { "type": "integer" } } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSocialAccountList" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" } } } }, "/me/social-accounts/{provider}/{uid_social_account}/": { "get": { "operationId": "me_social_accounts_retrieve", "description": "## Retrieve a social account provider\n", "parameters": [ { "in": "path", "name": "provider", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "uid_social_account", "schema": { "type": "string", "pattern": "^[-\\w]+$" }, "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialAccount" } } }, "description": null }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } }, "delete": { "operationId": "me_social_accounts_destroy", "description": "## Delete a social account provider\n", "parameters": [ { "in": "path", "name": "provider", "schema": { "type": "string" }, "required": true }, { "in": "path", "name": "uid_social_account", "schema": { "type": "string", "pattern": "^[-\\w]+$" }, "required": true } ], "tags": [ "User / team / organization / usage" ], "security": [ { "BasicAuth": [] }, { "TokenAuth": [] } ], "responses": { "204": { "description": "No response body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotAuthenticated": { "value": { "detail": "Authentication credentials were not provided." }, "summary": "Not authenticated" } } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "AccessDenied": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "Access Denied" } } } }, "description": "" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorDetail" }, "examples": { "NotFound": { "value": { "detail": "Not found." }, "summary": "Not Found" } } } }, "description": "" } } } }, "/api/v2/allauth/browser/v1/config": { "get": { "summary": "Get configuration", "tags": [ "Authentication (Allauth Headless)" ], "description": "There are many configuration options that alter the functionality\nand behavior of django-allauth, some of which can also impact the\nfrontend. Therefore, relevant configuration options are exposed via\nthis endpoint. The data returned is not user/authentication\ndependent. Hence, it suffices to only fetch this data once at boot\ntime of your application.\n", "parameters": [ { "$ref": "#/components/parameters/Client" } ], "responses": { "200": { "$ref": "#/components/responses/Configuration" } }, "operationId": "api_v2_allauth_browser_v1_config_get" } }, "/api/v2/allauth/app/v1/config": { "get": { "summary": "Get configuration", "tags": [ "Authentication (Allauth Headless)" ], "description": "There are many configuration options that alter the functionality\nand behavior of django-allauth, some of which can also impact the\nfrontend. Therefore, relevant configuration options are exposed via\nthis endpoint. The data returned is not user/authentication\ndependent. Hence, it suffices to only fetch this data once at boot\ntime of your application.\n", "parameters": [ { "$ref": "#/components/parameters/Client" } ], "responses": { "200": { "$ref": "#/components/responses/Configuration" } }, "operationId": "api_v2_allauth_app_v1_config_get" } }, "/api/v2/allauth/browser/v1/auth/login": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Login", "description": "Login using a username-password or email-password combination.\n", "parameters": [ { "$ref": "#/components/parameters/Client" } ], "requestBody": { "$ref": "#/components/requestBodies/Login" }, "responses": { "200": { "$ref": "#/components/responses/AuthenticatedByPassword" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_email": { "$ref": "#/components/examples/InvalidEmail" }, "password_mismatch": { "$ref": "#/components/examples/PasswordMismatch" } } } } }, "401": { "description": "Not authenticated.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationResponse" }, "examples": { "pending_email": { "$ref": "#/components/examples/UnauthenticatedPendingEmailVerification" }, "pending_2fa": { "$ref": "#/components/examples/UnauthenticatedPending2FA" } } } } }, "409": { "description": "Conflict. For example, when logging in when a user is already logged in.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_browser_v1_auth_login_post" } }, "/api/v2/allauth/app/v1/auth/login": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Login", "description": "Login using a username-password or email-password combination.\n", "parameters": [ { "$ref": "#/components/parameters/Client" } ], "requestBody": { "$ref": "#/components/requestBodies/Login" }, "responses": { "200": { "$ref": "#/components/responses/AuthenticatedByPassword" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_email": { "$ref": "#/components/examples/InvalidEmail" }, "password_mismatch": { "$ref": "#/components/examples/PasswordMismatch" } } } } }, "401": { "description": "Not authenticated.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationResponse" }, "examples": { "pending_email": { "$ref": "#/components/examples/UnauthenticatedPendingEmailVerification" }, "pending_2fa": { "$ref": "#/components/examples/UnauthenticatedPending2FA" } } } } }, "409": { "description": "Conflict. For example, when logging in when a user is already logged in.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_app_v1_auth_login_post" } }, "/api/v2/allauth/browser/v1/auth/signup": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Signup", "description": "Whether or not `username`, `email`, `phone` or combination of those are\nrequired depends on the configuration of django-allauth. Additionally,\nif a custom signup form is used there may be other custom properties\nrequired.\n", "parameters": [ { "$ref": "#/components/parameters/Client" } ], "requestBody": { "$ref": "#/components/requestBodies/Signup" }, "responses": { "200": { "$ref": "#/components/responses/AuthenticatedByPassword" }, "400": { "description": "An input error occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_email": { "$ref": "#/components/examples/InvalidEmail" } } } } }, "401": { "description": "Not authenticated.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationResponse" }, "examples": { "pending_email": { "$ref": "#/components/examples/UnauthenticatedPendingEmailVerification" } } } } }, "403": { "description": "Forbidden. For example, when signup is closed.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "409": { "description": "Conflict. For example, when signing up while user is logged in.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_browser_v1_auth_signup_post" } }, "/api/v2/allauth/app/v1/auth/signup": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Signup", "description": "Whether or not `username`, `email`, `phone` or combination of those are\nrequired depends on the configuration of django-allauth. Additionally,\nif a custom signup form is used there may be other custom properties\nrequired.\n", "parameters": [ { "$ref": "#/components/parameters/Client" } ], "requestBody": { "$ref": "#/components/requestBodies/Signup" }, "responses": { "200": { "$ref": "#/components/responses/AuthenticatedByPassword" }, "400": { "description": "An input error occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_email": { "$ref": "#/components/examples/InvalidEmail" } } } } }, "401": { "description": "Not authenticated.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationResponse" }, "examples": { "pending_email": { "$ref": "#/components/examples/UnauthenticatedPendingEmailVerification" } } } } }, "403": { "description": "Forbidden. For example, when signup is closed.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "409": { "description": "Conflict. For example, when signing up while user is logged in.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_app_v1_auth_signup_post" } }, "/api/v2/allauth/browser/v1/auth/email/verify": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Get email verification information", "description": "Obtain email verification information, given the token that was sent to\nthe user by email.\n", "parameters": [ { "$ref": "#/components/parameters/EmailVerificationKey" }, { "$ref": "#/components/parameters/Client" } ], "responses": { "200": { "$ref": "#/components/responses/EmailVerificationInfo" }, "400": { "description": "An input error occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_email": { "$ref": "#/components/examples/InvalidEmailVerificationKey" } } } } }, "409": { "description": "Conflict. The email verification (by code) flow is not pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_browser_v1_auth_email_verify_get" }, "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Verify an email", "description": "Complete the email verification process. Depending on the configuration,\nemail addresses are either verified by opening a link that is sent to\ntheir email address, or, by inputting a code that is sent. On the API,\nboth cases are handled identically. Meaning, the required key is either\nthe one from the link, or, the code itself.\n\nNote that a status code of 401 does not imply failure. It indicates that\nthe email verification was successful, yet, the user is still not signed\nin. For example, in case `ACCOUNT_LOGIN_ON_EMAIL_CONFIRMATION` is set to\n`False`, a 401 is returned when verifying as part of login/signup.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/VerifyEmail" }, "responses": { "200": { "$ref": "#/components/responses/Authenticated" }, "400": { "description": "An input error occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_email": { "$ref": "#/components/examples/InvalidEmailVerificationKey" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "409": { "description": "Conflict. The email verification (by code) flow is not pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_browser_v1_auth_email_verify_post" } }, "/api/v2/allauth/app/v1/auth/email/verify": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Get email verification information", "description": "Obtain email verification information, given the token that was sent to\nthe user by email.\n", "parameters": [ { "$ref": "#/components/parameters/EmailVerificationKey" }, { "$ref": "#/components/parameters/Client" } ], "responses": { "200": { "$ref": "#/components/responses/EmailVerificationInfo" }, "400": { "description": "An input error occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_email": { "$ref": "#/components/examples/InvalidEmailVerificationKey" } } } } }, "409": { "description": "Conflict. The email verification (by code) flow is not pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_app_v1_auth_email_verify_get" }, "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Verify an email", "description": "Complete the email verification process. Depending on the configuration,\nemail addresses are either verified by opening a link that is sent to\ntheir email address, or, by inputting a code that is sent. On the API,\nboth cases are handled identically. Meaning, the required key is either\nthe one from the link, or, the code itself.\n\nNote that a status code of 401 does not imply failure. It indicates that\nthe email verification was successful, yet, the user is still not signed\nin. For example, in case `ACCOUNT_LOGIN_ON_EMAIL_CONFIRMATION` is set to\n`False`, a 401 is returned when verifying as part of login/signup.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/VerifyEmail" }, "responses": { "200": { "$ref": "#/components/responses/Authenticated" }, "400": { "description": "An input error occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_email": { "$ref": "#/components/examples/InvalidEmailVerificationKey" } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "409": { "description": "Conflict. The email verification (by code) flow is not pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_app_v1_auth_email_verify_post" } }, "/api/v2/allauth/browser/v1/auth/email/verify/resend": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Resend email verification code", "description": "Requests a new email verification code.\nRequires `ACCOUNT_EMAIL_VERIFICATION_SUPPORTS_RESEND = True`.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/StatusOK" }, "409": { "description": "Conflict. The email verification (by code) flow is not pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "api_v2_allauth_browser_v1_auth_email_verify_resend_post" } }, "/api/v2/allauth/app/v1/auth/email/verify/resend": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Resend email verification code", "description": "Requests a new email verification code.\nRequires `ACCOUNT_EMAIL_VERIFICATION_SUPPORTS_RESEND = True`.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/StatusOK" }, "409": { "description": "Conflict. The email verification (by code) flow is not pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "api_v2_allauth_app_v1_auth_email_verify_resend_post" } }, "/api/v2/allauth/browser/v1/auth/phone/verify": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Verify a phone number", "description": "Complete the phone number verification process. Note that a status code\nof 401 does not imply failure. It merely indicates that the phone number\nverification was successful, yet, the user is still not signed in.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/VerifyPhone" }, "responses": { "200": { "$ref": "#/components/responses/Authenticated" }, "400": { "description": "An input error occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "409": { "description": "Conflict. The phone verification flow is not pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_browser_v1_auth_phone_verify_post" } }, "/api/v2/allauth/app/v1/auth/phone/verify": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Verify a phone number", "description": "Complete the phone number verification process. Note that a status code\nof 401 does not imply failure. It merely indicates that the phone number\nverification was successful, yet, the user is still not signed in.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/VerifyPhone" }, "responses": { "200": { "$ref": "#/components/responses/Authenticated" }, "400": { "description": "An input error occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "409": { "description": "Conflict. The phone verification flow is not pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_app_v1_auth_phone_verify_post" } }, "/api/v2/allauth/browser/v1/auth/phone/verify/resend": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Resend phone number verification code", "description": "Requests a new phone number verification code.\nRequires `ACCOUNT_PHONE_VERIFICATION_SUPPORTS_RESEND = True`.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/StatusOK" }, "409": { "description": "Conflict. The phone verification flow is not pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "api_v2_allauth_browser_v1_auth_phone_verify_resend_post" } }, "/api/v2/allauth/app/v1/auth/phone/verify/resend": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Resend phone number verification code", "description": "Requests a new phone number verification code.\nRequires `ACCOUNT_PHONE_VERIFICATION_SUPPORTS_RESEND = True`.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/StatusOK" }, "409": { "description": "Conflict. The phone verification flow is not pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "operationId": "api_v2_allauth_app_v1_auth_phone_verify_resend_post" } }, "/api/v2/allauth/browser/v1/auth/reauthenticate": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Reauthenticate", "description": "In order to safeguard the account, some actions require the user to be\nrecently authenticated. If you try to perform such an action without\nhaving been recently authenticated, a `401` status is returned, listing\nflows that can be performed to reauthenticate. One such flow is the flow\nwith ID `reauthenticate`, which allows for the user to input the\npassword. This is the endpoint related towards that flow.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/Reauthenticate" }, "responses": { "200": { "$ref": "#/components/responses/AuthenticatedByPassword" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_email": { "$ref": "#/components/examples/IncorrectPassword" } } } } } }, "operationId": "api_v2_allauth_browser_v1_auth_reauthenticate_post" } }, "/api/v2/allauth/app/v1/auth/reauthenticate": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Reauthenticate", "description": "In order to safeguard the account, some actions require the user to be\nrecently authenticated. If you try to perform such an action without\nhaving been recently authenticated, a `401` status is returned, listing\nflows that can be performed to reauthenticate. One such flow is the flow\nwith ID `reauthenticate`, which allows for the user to input the\npassword. This is the endpoint related towards that flow.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/Reauthenticate" }, "responses": { "200": { "$ref": "#/components/responses/AuthenticatedByPassword" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_email": { "$ref": "#/components/examples/IncorrectPassword" } } } } } }, "operationId": "api_v2_allauth_app_v1_auth_reauthenticate_post" } }, "/api/v2/allauth/browser/v1/auth/password/request": { "post": { "summary": "Request password", "description": "Initiates the password reset procedure. Depending on whether or not\n`ACCOUNT_PASSWORD_RESET_BY_CODE_ENABLED` is `True`, the procedure is\neither stateless or stateful.\n\nIn case codes are used, it is stateful, and a new\n`password_reset_by_code` flow is started. In this case, on a successful\npassword reset request, you will receive a 401 indicating the pending\nstatus of this flow.\n\nIn case password reset is configured to use (stateless) links, you will\nreceive a 200 on a successful password reset request.\n", "tags": [ "Authentication (Allauth Headless)" ], "parameters": [ { "$ref": "#/components/parameters/Client" } ], "requestBody": { "$ref": "#/components/requestBodies/RequestPassword" }, "responses": { "200": { "$ref": "#/components/responses/StatusOK" }, "400": { "description": "An input error occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_email": { "$ref": "#/components/examples/InvalidEmail" } } } } }, "401": { "$ref": "#/components/responses/Authentication" } }, "operationId": "api_v2_allauth_browser_v1_auth_password_request_post" } }, "/api/v2/allauth/app/v1/auth/password/request": { "post": { "summary": "Request password", "description": "Initiates the password reset procedure. Depending on whether or not\n`ACCOUNT_PASSWORD_RESET_BY_CODE_ENABLED` is `True`, the procedure is\neither stateless or stateful.\n\nIn case codes are used, it is stateful, and a new\n`password_reset_by_code` flow is started. In this case, on a successful\npassword reset request, you will receive a 401 indicating the pending\nstatus of this flow.\n\nIn case password reset is configured to use (stateless) links, you will\nreceive a 200 on a successful password reset request.\n", "tags": [ "Authentication (Allauth Headless)" ], "parameters": [ { "$ref": "#/components/parameters/Client" } ], "requestBody": { "$ref": "#/components/requestBodies/RequestPassword" }, "responses": { "200": { "$ref": "#/components/responses/StatusOK" }, "400": { "description": "An input error occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_email": { "$ref": "#/components/examples/InvalidEmail" } } } } }, "401": { "$ref": "#/components/responses/Authentication" } }, "operationId": "api_v2_allauth_app_v1_auth_password_request_post" } }, "/api/v2/allauth/browser/v1/auth/password/reset": { "get": { "summary": "Get password reset information", "description": "Used to obtain information on and validate a password reset key. The\nkey passed is either the key encoded in the password reset URL that the\nuser has received per email, or, the password reset code in case of\n`ACCOUNT_PASSWORD_RESET_BY_CODE_ENABLED`. Note that in case of a code,\nthe number of requests you can make is limited (by\n`ACCOUNT_PASSWORD_RESET_BY_CODE_MAX_ATTEMPTS`).\n", "tags": [ "Authentication (Allauth Headless)" ], "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/PasswordResetKey" } ], "responses": { "200": { "$ref": "#/components/responses/PasswordResetInfo" }, "400": { "description": "An input error occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "password_reset_key_invalid": { "$ref": "#/components/examples/InvalidPasswordResetKey" } } } } }, "409": { "description": "Conflict. There is no password reset (by code) flow pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_browser_v1_auth_password_reset_get" }, "post": { "summary": "Reset password", "description": "Perform the password reset, by handing over the password reset key and\nthe new password. After successfully completing the password reset, the\nuser is either logged in (in case `ACCOUNT_LOGIN_ON_PASSWORD_RESET` is\n`True`), or, the user will need to proceed to the login page. In case\nof the former, a `200` status code is returned, in case of the latter a\n401.\n", "tags": [ "Authentication (Allauth Headless)" ], "parameters": [ { "$ref": "#/components/parameters/Client" } ], "requestBody": { "$ref": "#/components/requestBodies/ResetPassword" }, "responses": { "200": { "$ref": "#/components/responses/AuthenticatedByPassword" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_email": { "$ref": "#/components/examples/InvalidEmail" } } } } }, "401": { "$ref": "#/components/responses/Authentication" }, "409": { "description": "Conflict. There is no password reset (by code) flow pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_browser_v1_auth_password_reset_post" } }, "/api/v2/allauth/app/v1/auth/password/reset": { "get": { "summary": "Get password reset information", "description": "Used to obtain information on and validate a password reset key. The\nkey passed is either the key encoded in the password reset URL that the\nuser has received per email, or, the password reset code in case of\n`ACCOUNT_PASSWORD_RESET_BY_CODE_ENABLED`. Note that in case of a code,\nthe number of requests you can make is limited (by\n`ACCOUNT_PASSWORD_RESET_BY_CODE_MAX_ATTEMPTS`).\n", "tags": [ "Authentication (Allauth Headless)" ], "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/PasswordResetKey" } ], "responses": { "200": { "$ref": "#/components/responses/PasswordResetInfo" }, "400": { "description": "An input error occurred.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "password_reset_key_invalid": { "$ref": "#/components/examples/InvalidPasswordResetKey" } } } } }, "409": { "description": "Conflict. There is no password reset (by code) flow pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_app_v1_auth_password_reset_get" }, "post": { "summary": "Reset password", "description": "Perform the password reset, by handing over the password reset key and\nthe new password. After successfully completing the password reset, the\nuser is either logged in (in case `ACCOUNT_LOGIN_ON_PASSWORD_RESET` is\n`True`), or, the user will need to proceed to the login page. In case\nof the former, a `200` status code is returned, in case of the latter a\n401.\n", "tags": [ "Authentication (Allauth Headless)" ], "parameters": [ { "$ref": "#/components/parameters/Client" } ], "requestBody": { "$ref": "#/components/requestBodies/ResetPassword" }, "responses": { "200": { "$ref": "#/components/responses/AuthenticatedByPassword" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_email": { "$ref": "#/components/examples/InvalidEmail" } } } } }, "401": { "$ref": "#/components/responses/Authentication" }, "409": { "description": "Conflict. There is no password reset (by code) flow pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_app_v1_auth_password_reset_post" } }, "/api/v2/allauth/browser/v1/auth/provider/redirect": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Provider redirect", "description": "Initiates the third-party provider authentication redirect flow. As calling\nthis endpoint results in a user facing redirect (302), this call is only\navailable in a browser, and must be called in a synchronous (non-XHR)\nmanner.\n", "requestBody": { "$ref": "#/components/requestBodies/ProviderRedirect" }, "responses": { "302": { "description": "The provider authorization URL to which the client should be redirected.", "headers": { "location": { "schema": { "type": "string" }, "description": "The redirect URL." } } } }, "operationId": "api_v2_allauth_browser_v1_auth_provider_redirect_post" } }, "/api/v2/allauth/browser/v1/auth/provider/token": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Provider token", "description": "Authenticates with a third-party provider using provider tokens received\nby other means. For example, in case of a mobile app, the authentication\nflow runs completely on the device itself, without any interaction with\nthe API. Then, when the (device) authentication completes and the mobile\napp receives an access and/or ID token, it can hand over these tokens\nvia this endpoint to authenticate on the server.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/ProviderToken" }, "responses": { "200": { "$ref": "#/components/responses/Authenticated" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_token": { "$ref": "#/components/examples/InvalidProviderToken" } } } } }, "401": { "description": "Not authenticated, more steps are required to be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationResponse" }, "examples": { "unauthenticated_pending_2fa": { "$ref": "#/components/examples/UnauthenticatedPending2FA" }, "unauthenticated_pending_email_verification": { "$ref": "#/components/examples/UnauthenticatedPendingEmailVerification" } } } } }, "403": { "description": "Forbidden. For example, when signup is closed.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } } }, "operationId": "api_v2_allauth_browser_v1_auth_provider_token_post" } }, "/api/v2/allauth/app/v1/auth/provider/token": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Provider token", "description": "Authenticates with a third-party provider using provider tokens received\nby other means. For example, in case of a mobile app, the authentication\nflow runs completely on the device itself, without any interaction with\nthe API. Then, when the (device) authentication completes and the mobile\napp receives an access and/or ID token, it can hand over these tokens\nvia this endpoint to authenticate on the server.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/ProviderToken" }, "responses": { "200": { "$ref": "#/components/responses/Authenticated" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_token": { "$ref": "#/components/examples/InvalidProviderToken" } } } } }, "401": { "description": "Not authenticated, more steps are required to be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationResponse" }, "examples": { "unauthenticated_pending_2fa": { "$ref": "#/components/examples/UnauthenticatedPending2FA" }, "unauthenticated_pending_email_verification": { "$ref": "#/components/examples/UnauthenticatedPendingEmailVerification" } } } } }, "403": { "description": "Forbidden. For example, when signup is closed.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } } }, "operationId": "api_v2_allauth_app_v1_auth_provider_token_post" } }, "/api/v2/allauth/browser/v1/auth/provider/signup": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Provider signup information", "description": "If, while signing up using a third-party provider account, there is\ninsufficient information received from the provider to automatically\ncomplete the signup process, an additional step is needed to complete\nthe missing data before the user is fully signed up and authenticated.\nThe information available so far, such as the pending provider account,\ncan be retrieved via this endpoint.\n", "parameters": [ { "$ref": "#/components/parameters/Client" } ], "responses": { "200": { "$ref": "#/components/responses/ProviderSignup" }, "409": { "description": "Conflict. The provider signup flow is not pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_browser_v1_auth_provider_signup_get" }, "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Provider signup", "description": "If, while signing up using a third-party provider account, there is\ninsufficient information received from the provider to automatically\ncomplete the signup process, an additional step is needed to complete\nthe missing data before the user is fully signed up and authenticated.\n", "parameters": [ { "$ref": "#/components/parameters/Client" } ], "requestBody": { "$ref": "#/components/requestBodies/ProviderSignup" }, "responses": { "200": { "$ref": "#/components/responses/Authenticated" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_email": { "$ref": "#/components/examples/InvalidEmail" } } } } }, "401": { "description": "Not authenticated, more steps are required to be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationResponse" }, "examples": { "unauthenticated_pending_email_verification": { "$ref": "#/components/examples/UnauthenticatedPendingEmailVerification" } } } } }, "403": { "description": "Forbidden. For example, when signup is closed.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "409": { "description": "Conflict. The provider signup flow is not pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_browser_v1_auth_provider_signup_post" } }, "/api/v2/allauth/app/v1/auth/provider/signup": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Provider signup information", "description": "If, while signing up using a third-party provider account, there is\ninsufficient information received from the provider to automatically\ncomplete the signup process, an additional step is needed to complete\nthe missing data before the user is fully signed up and authenticated.\nThe information available so far, such as the pending provider account,\ncan be retrieved via this endpoint.\n", "parameters": [ { "$ref": "#/components/parameters/Client" } ], "responses": { "200": { "$ref": "#/components/responses/ProviderSignup" }, "409": { "description": "Conflict. The provider signup flow is not pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_app_v1_auth_provider_signup_get" }, "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Provider signup", "description": "If, while signing up using a third-party provider account, there is\ninsufficient information received from the provider to automatically\ncomplete the signup process, an additional step is needed to complete\nthe missing data before the user is fully signed up and authenticated.\n", "parameters": [ { "$ref": "#/components/parameters/Client" } ], "requestBody": { "$ref": "#/components/requestBodies/ProviderSignup" }, "responses": { "200": { "$ref": "#/components/responses/Authenticated" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_email": { "$ref": "#/components/examples/InvalidEmail" } } } } }, "401": { "description": "Not authenticated, more steps are required to be completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationResponse" }, "examples": { "unauthenticated_pending_email_verification": { "$ref": "#/components/examples/UnauthenticatedPendingEmailVerification" } } } } }, "403": { "description": "Forbidden. For example, when signup is closed.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "409": { "description": "Conflict. The provider signup flow is not pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_app_v1_auth_provider_signup_post" } }, "/api/v2/allauth/browser/v1/auth/2fa/authenticate": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Two-factor authentication", "description": "If, during authentication, a response with status 401 is encountered where one of the pending\nflows has ID `mfa_authenticate`, that indicates that the Two-Factor Authentication stage needs to\nbe completed.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/MFAAuthenticate" }, "responses": { "200": { "$ref": "#/components/responses/AuthenticatedByPasswordAnd2FA" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_code": { "$ref": "#/components/examples/InvalidAuthenticatorCode" } } } } }, "401": { "$ref": "#/components/responses/Authentication" } }, "operationId": "api_v2_allauth_browser_v1_auth_2fa_authenticate_post" } }, "/api/v2/allauth/app/v1/auth/2fa/authenticate": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Two-factor authentication", "description": "If, during authentication, a response with status 401 is encountered where one of the pending\nflows has ID `mfa_authenticate`, that indicates that the Two-Factor Authentication stage needs to\nbe completed.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/MFAAuthenticate" }, "responses": { "200": { "$ref": "#/components/responses/AuthenticatedByPasswordAnd2FA" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_code": { "$ref": "#/components/examples/InvalidAuthenticatorCode" } } } } }, "401": { "$ref": "#/components/responses/Authentication" } }, "operationId": "api_v2_allauth_app_v1_auth_2fa_authenticate_post" } }, "/api/v2/allauth/browser/v1/auth/2fa/reauthenticate": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Reauthenticate using 2FA", "description": "In order to safeguard the account, some actions require the user to be\nrecently authenticated. If you try to perform such an action without\nhaving been recently authenticated, a `401` status is returned, listing\nflows that can be performed to reauthenticate. One such flow is the flow\nwith ID `mfa_reauthenticate`, which allows for the user to input an\nauthenticator code (e.g. TOTP or recovery code). This is the endpoint\nrelated towards that flow.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/MFAAuthenticate" }, "responses": { "200": { "$ref": "#/components/responses/AuthenticatedByPasswordAnd2FA" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_code": { "$ref": "#/components/examples/InvalidAuthenticatorCode" } } } } } }, "operationId": "api_v2_allauth_browser_v1_auth_2fa_reauthenticate_post" } }, "/api/v2/allauth/app/v1/auth/2fa/reauthenticate": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Reauthenticate using 2FA", "description": "In order to safeguard the account, some actions require the user to be\nrecently authenticated. If you try to perform such an action without\nhaving been recently authenticated, a `401` status is returned, listing\nflows that can be performed to reauthenticate. One such flow is the flow\nwith ID `mfa_reauthenticate`, which allows for the user to input an\nauthenticator code (e.g. TOTP or recovery code). This is the endpoint\nrelated towards that flow.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/MFAAuthenticate" }, "responses": { "200": { "$ref": "#/components/responses/AuthenticatedByPasswordAnd2FA" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_code": { "$ref": "#/components/examples/InvalidAuthenticatorCode" } } } } } }, "operationId": "api_v2_allauth_app_v1_auth_2fa_reauthenticate_post" } }, "/api/v2/allauth/browser/v1/auth/code/confirm": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Confirm login code", "description": "Use this endpoint to pass along the received \"special\" login code.\n", "parameters": [ { "$ref": "#/components/parameters/Client" } ], "requestBody": { "$ref": "#/components/requestBodies/ConfirmLoginCode" }, "responses": { "200": { "$ref": "#/components/responses/AuthenticatedByCode" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_code": { "$ref": "#/components/examples/InvalidAuthenticatorCode" } } } } }, "401": { "description": "Not authenticated.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationResponse" }, "examples": { "unauthenticated_pending_2fa": { "$ref": "#/components/examples/UnauthenticatedPending2FA" } } } } }, "409": { "description": "Conflict. The \"login by code\" flow is not pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_browser_v1_auth_code_confirm_post" } }, "/api/v2/allauth/app/v1/auth/code/confirm": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Confirm login code", "description": "Use this endpoint to pass along the received \"special\" login code.\n", "parameters": [ { "$ref": "#/components/parameters/Client" } ], "requestBody": { "$ref": "#/components/requestBodies/ConfirmLoginCode" }, "responses": { "200": { "$ref": "#/components/responses/AuthenticatedByCode" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_code": { "$ref": "#/components/examples/InvalidAuthenticatorCode" } } } } }, "401": { "description": "Not authenticated.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationResponse" }, "examples": { "unauthenticated_pending_2fa": { "$ref": "#/components/examples/UnauthenticatedPending2FA" } } } } }, "409": { "description": "Conflict. The \"login by code\" flow is not pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_app_v1_auth_code_confirm_post" } }, "/api/v2/allauth/browser/v1/account/providers": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "List the connected third-party provider accounts", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/ProviderAccounts" } }, "operationId": "api_v2_allauth_browser_v1_account_providers_get" }, "delete": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Disconnect a third-party provider account\n", "description": "Disconnect a third-party provider account, returning the remaining\naccounts that are still connected. The disconnect is not allowed if it\nwould leave the account unusable. For example, if no password was\nset up yet.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/ProviderAccount" }, "responses": { "200": { "$ref": "#/components/responses/ProviderAccounts" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_password": { "$ref": "#/components/examples/DisconnectNotAllowedNoPassword" }, "no_email": { "$ref": "#/components/examples/DisconnectNotAllowedNoVerifiedEmail" } } } } } }, "operationId": "api_v2_allauth_browser_v1_account_providers_delete" } }, "/api/v2/allauth/app/v1/account/providers": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "List the connected third-party provider accounts", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/ProviderAccounts" } }, "operationId": "api_v2_allauth_app_v1_account_providers_get" }, "delete": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Disconnect a third-party provider account\n", "description": "Disconnect a third-party provider account, returning the remaining\naccounts that are still connected. The disconnect is not allowed if it\nwould leave the account unusable. For example, if no password was\nset up yet.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/ProviderAccount" }, "responses": { "200": { "$ref": "#/components/responses/ProviderAccounts" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_password": { "$ref": "#/components/examples/DisconnectNotAllowedNoPassword" }, "no_email": { "$ref": "#/components/examples/DisconnectNotAllowedNoVerifiedEmail" } } } } } }, "operationId": "api_v2_allauth_app_v1_account_providers_delete" } }, "/api/v2/allauth/browser/v1/account/email": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "List email addresses", "description": "Retrieves the list of email addresses of the account.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/EmailAddresses" }, "401": { "$ref": "#/components/responses/Authentication" } }, "operationId": "api_v2_allauth_browser_v1_account_email_get" }, "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Add/Change email address\n", "description": "The following functionality is available:\n\n - Adding a new email address for an already signed in user (`ACCOUNT_CHANGE_EMAIL = False`).\n - Change to a new email address for an already signed in user (`ACCOUNT_CHANGE_EMAIL = True`).\n - Change to a new email address during the email verification process at signup (`ACCOUNT_EMAIL_VERIFICATION_SUPPORTS_CHANGE = True`).\n\nIn all cases, an email verification mail will be sent containing a link or code that needs to be verified.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/Email" }, "responses": { "200": { "$ref": "#/components/responses/EmailAddresses" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_code": { "$ref": "#/components/examples/InvalidEmail" } } } } }, "401": { "$ref": "#/components/responses/AuthenticationOrReauthentication" }, "409": { "description": "Conflict. For example, when no user is authenticated and no email verification flow is pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_browser_v1_account_email_post" }, "put": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Request email verification", "description": "Requests for (another) email verification email to be sent. Note that\nsending emails is rate limited, so when you send too many requests the\nemail will not be sent.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/Email" }, "responses": { "200": { "$ref": "#/components/responses/StatusOK" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_code": { "$ref": "#/components/examples/InvalidEmail" } } } } }, "403": { "description": "Too many email verification mails were already sent.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } } }, "operationId": "api_v2_allauth_browser_v1_account_email_put" }, "patch": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Change primary email address", "description": "Used to change primary email address to a different one. Note that only verified email addresses\ncan be marked as primary.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/MarkPrimaryEmail" }, "responses": { "200": { "$ref": "#/components/responses/EmailAddresses" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_code": { "$ref": "#/components/examples/InvalidEmail" } } } } } }, "operationId": "api_v2_allauth_browser_v1_account_email_patch" }, "delete": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Remove an email address", "description": "Used to remove an email address.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/Email" }, "responses": { "200": { "$ref": "#/components/responses/EmailAddresses" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_code": { "$ref": "#/components/examples/InvalidEmail" } } } } } }, "operationId": "api_v2_allauth_browser_v1_account_email_delete" } }, "/api/v2/allauth/app/v1/account/email": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "List email addresses", "description": "Retrieves the list of email addresses of the account.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/EmailAddresses" }, "401": { "$ref": "#/components/responses/Authentication" } }, "operationId": "api_v2_allauth_app_v1_account_email_get" }, "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Add/Change email address\n", "description": "The following functionality is available:\n\n - Adding a new email address for an already signed in user (`ACCOUNT_CHANGE_EMAIL = False`).\n - Change to a new email address for an already signed in user (`ACCOUNT_CHANGE_EMAIL = True`).\n - Change to a new email address during the email verification process at signup (`ACCOUNT_EMAIL_VERIFICATION_SUPPORTS_CHANGE = True`).\n\nIn all cases, an email verification mail will be sent containing a link or code that needs to be verified.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/Email" }, "responses": { "200": { "$ref": "#/components/responses/EmailAddresses" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_code": { "$ref": "#/components/examples/InvalidEmail" } } } } }, "401": { "$ref": "#/components/responses/AuthenticationOrReauthentication" }, "409": { "description": "Conflict. For example, when no user is authenticated and no email verification flow is pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_app_v1_account_email_post" }, "put": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Request email verification", "description": "Requests for (another) email verification email to be sent. Note that\nsending emails is rate limited, so when you send too many requests the\nemail will not be sent.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/Email" }, "responses": { "200": { "$ref": "#/components/responses/StatusOK" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_code": { "$ref": "#/components/examples/InvalidEmail" } } } } }, "403": { "description": "Too many email verification mails were already sent.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } } }, "operationId": "api_v2_allauth_app_v1_account_email_put" }, "patch": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Change primary email address", "description": "Used to change primary email address to a different one. Note that only verified email addresses\ncan be marked as primary.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/MarkPrimaryEmail" }, "responses": { "200": { "$ref": "#/components/responses/EmailAddresses" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_code": { "$ref": "#/components/examples/InvalidEmail" } } } } } }, "operationId": "api_v2_allauth_app_v1_account_email_patch" }, "delete": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Remove an email address", "description": "Used to remove an email address.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/Email" }, "responses": { "200": { "$ref": "#/components/responses/EmailAddresses" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_code": { "$ref": "#/components/examples/InvalidEmail" } } } } } }, "operationId": "api_v2_allauth_app_v1_account_email_delete" } }, "/api/v2/allauth/browser/v1/account/phone": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Get the phone number", "description": "Retrieves the phone number of the account, if any. Note that while the\nendpoint returns a list of phone numbers, at most one entry is returned.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/PhoneNumbers" }, "401": { "$ref": "#/components/responses/Authentication" } }, "operationId": "api_v2_allauth_browser_v1_account_phone_get" }, "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Change the phone number\n", "description": "The following functionality is available:\n\n- Initiate the phone number change process for signed in users.\n- Change to a new phone number during the phone number verification\n process at signup for unauthenticated users. Note that this requires:\n `ACCOUNT_PHONE_VERIFICATION_SUPPORTS_CHANGE = True`.\n\nIn both cases, after posting a new phone number, proceed with the phone\nverification endpoint to confirm the change of the phone number by\nposting the verification code.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/Phone" }, "responses": { "202": { "description": "Phone number change process initiated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberChangeResponse" } } } }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationOrReauthentication" }, "409": { "description": "Conflict. For example, when no user is authenticated and no phone verification flow is pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_browser_v1_account_phone_post" } }, "/api/v2/allauth/app/v1/account/phone": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Get the phone number", "description": "Retrieves the phone number of the account, if any. Note that while the\nendpoint returns a list of phone numbers, at most one entry is returned.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/PhoneNumbers" }, "401": { "$ref": "#/components/responses/Authentication" } }, "operationId": "api_v2_allauth_app_v1_account_phone_get" }, "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Change the phone number\n", "description": "The following functionality is available:\n\n- Initiate the phone number change process for signed in users.\n- Change to a new phone number during the phone number verification\n process at signup for unauthenticated users. Note that this requires:\n `ACCOUNT_PHONE_VERIFICATION_SUPPORTS_CHANGE = True`.\n\nIn both cases, after posting a new phone number, proceed with the phone\nverification endpoint to confirm the change of the phone number by\nposting the verification code.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/Phone" }, "responses": { "202": { "description": "Phone number change process initiated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberChangeResponse" } } } }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationOrReauthentication" }, "409": { "description": "Conflict. For example, when no user is authenticated and no phone verification flow is pending.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } } }, "operationId": "api_v2_allauth_app_v1_account_phone_post" } }, "/api/v2/allauth/browser/v1/account/authenticators": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "List authenticators", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/Authenticators" }, "401": { "$ref": "#/components/responses/Authentication" }, "410": { "$ref": "#/components/responses/SessionGone" } }, "operationId": "api_v2_allauth_browser_v1_account_authenticators_get" } }, "/api/v2/allauth/app/v1/account/authenticators": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "List authenticators", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/Authenticators" }, "401": { "$ref": "#/components/responses/Authentication" }, "410": { "$ref": "#/components/responses/SessionGone" } }, "operationId": "api_v2_allauth_app_v1_account_authenticators_get" } }, "/api/v2/allauth/browser/v1/account/authenticators/totp": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "TOTP authenticator status", "description": "Retrieve the information about the current TOTP authenticator, if any.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "404": { "$ref": "#/components/responses/TOTPAuthenticatorNotFound" }, "200": { "$ref": "#/components/responses/TOTPAuthenticator" }, "409": { "$ref": "#/components/responses/AddAuthenticatorConflict" } }, "operationId": "api_v2_allauth_browser_v1_account_authenticators_totp_get" }, "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Activate TOTP", "description": "The code should be provided from the consuming TOTP authenticator\napplication which was generated using the TOTP authenticator secret\nretrieved from the TOTP authenticator status endpoint.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/SetupTOTP" }, "responses": { "200": { "$ref": "#/components/responses/TOTPAuthenticator" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_code": { "$ref": "#/components/examples/InvalidAuthenticatorCode" } } } } }, "401": { "$ref": "#/components/responses/ReauthenticationRequired" }, "409": { "$ref": "#/components/responses/AddAuthenticatorConflict" } }, "operationId": "api_v2_allauth_browser_v1_account_authenticators_totp_post" }, "delete": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Deactivate TOTP", "description": "Deactivates TOTP authentication. If the user authentication is not\nsufficiently recent, a reauthentication flow (`401`) will is presented.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/StatusOK" }, "401": { "$ref": "#/components/responses/ReauthenticationRequired" } }, "operationId": "api_v2_allauth_browser_v1_account_authenticators_totp_delete" } }, "/api/v2/allauth/app/v1/account/authenticators/totp": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "TOTP authenticator status", "description": "Retrieve the information about the current TOTP authenticator, if any.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "404": { "$ref": "#/components/responses/TOTPAuthenticatorNotFound" }, "200": { "$ref": "#/components/responses/TOTPAuthenticator" }, "409": { "$ref": "#/components/responses/AddAuthenticatorConflict" } }, "operationId": "api_v2_allauth_app_v1_account_authenticators_totp_get" }, "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Activate TOTP", "description": "The code should be provided from the consuming TOTP authenticator\napplication which was generated using the TOTP authenticator secret\nretrieved from the TOTP authenticator status endpoint.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/SetupTOTP" }, "responses": { "200": { "$ref": "#/components/responses/TOTPAuthenticator" }, "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_code": { "$ref": "#/components/examples/InvalidAuthenticatorCode" } } } } }, "401": { "$ref": "#/components/responses/ReauthenticationRequired" }, "409": { "$ref": "#/components/responses/AddAuthenticatorConflict" } }, "operationId": "api_v2_allauth_app_v1_account_authenticators_totp_post" }, "delete": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Deactivate TOTP", "description": "Deactivates TOTP authentication. If the user authentication is not\nsufficiently recent, a reauthentication flow (`401`) will is presented.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/StatusOK" }, "401": { "$ref": "#/components/responses/ReauthenticationRequired" } }, "operationId": "api_v2_allauth_app_v1_account_authenticators_totp_delete" } }, "/api/v2/allauth/browser/v1/account/authenticators/recovery-codes": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "List recovery codes", "description": "List recovery codes.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/RecoveryCodes" }, "401": { "$ref": "#/components/responses/ReauthenticationRequired" }, "404": { "$ref": "#/components/responses/NotFound" } }, "operationId": "api_v2_allauth_browser_v1_account_authenticators_recovery_codes_get" }, "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Regenerate recovery codes", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_code": { "$ref": "#/components/examples/CannotGenerateRecoveryCodes" } } } } }, "401": { "$ref": "#/components/responses/ReauthenticationRequired" } }, "operationId": "api_v2_allauth_browser_v1_account_authenticators_recovery_codes_post" } }, "/api/v2/allauth/app/v1/account/authenticators/recovery-codes": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "List recovery codes", "description": "List recovery codes.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/RecoveryCodes" }, "401": { "$ref": "#/components/responses/ReauthenticationRequired" }, "404": { "$ref": "#/components/responses/NotFound" } }, "operationId": "api_v2_allauth_app_v1_account_authenticators_recovery_codes_get" }, "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Regenerate recovery codes", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "400": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalid_code": { "$ref": "#/components/examples/CannotGenerateRecoveryCodes" } } } } }, "401": { "$ref": "#/components/responses/ReauthenticationRequired" } }, "operationId": "api_v2_allauth_app_v1_account_authenticators_recovery_codes_post" } }, "/api/v2/allauth/browser/v1/auth/session": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Get authentication status\n", "description": "Retrieve information about the authentication status for the current\nsession.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/Authenticated" }, "401": { "$ref": "#/components/responses/Authentication" }, "410": { "$ref": "#/components/responses/SessionGone" } }, "operationId": "api_v2_allauth_browser_v1_auth_session_get" }, "delete": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Logout", "description": "Logs out the user from the current session.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "401": { "$ref": "#/components/responses/Unauthenticated" } }, "operationId": "api_v2_allauth_browser_v1_auth_session_delete" } }, "/api/v2/allauth/app/v1/auth/session": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Get authentication status\n", "description": "Retrieve information about the authentication status for the current\nsession.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/Authenticated" }, "401": { "$ref": "#/components/responses/Authentication" }, "410": { "$ref": "#/components/responses/SessionGone" } }, "operationId": "api_v2_allauth_app_v1_auth_session_get" }, "delete": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Logout", "description": "Logs out the user from the current session.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "401": { "$ref": "#/components/responses/Unauthenticated" } }, "operationId": "api_v2_allauth_app_v1_auth_session_delete" } }, "/api/v2/allauth/app/v1/tokens/refresh": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Refresh the access token\n", "description": "Used to retrieve a new access token. Depending on `settings.HEADLESS_JWT_ROTATE_REFRESH_TOKEN`,\na new refresh token is returned as well.\n", "requestBody": { "$ref": "#/components/requestBodies/RefreshToken" }, "responses": { "200": { "$ref": "#/components/responses/RefreshToken" }, "400": { "description": "The refresh token is invalid or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "operationId": "api_v2_allauth_app_v1_tokens_refresh_post" } }, "/api/v2/allauth/browser/v1/account/password/change": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Change password", "description": "In order to change the password of an account, the current and new\npassword must be provider. However, accounts that were created by\nsigning up using a third-party provider do not have a password set. In\nthat case, the current password is not required.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/ChangePassword" }, "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Authentication" } }, "operationId": "api_v2_allauth_browser_v1_account_password_change_post" } }, "/api/v2/allauth/app/v1/account/password/change": { "post": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "Change password", "description": "In order to change the password of an account, the current and new\npassword must be provider. However, accounts that were created by\nsigning up using a third-party provider do not have a password set. In\nthat case, the current password is not required.\n", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/ChangePassword" }, "responses": { "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Authentication" } }, "operationId": "api_v2_allauth_app_v1_account_password_change_post" } }, "/api/v2/allauth/browser/v1/auth/sessions": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "List sessions", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/Sessions" } }, "operationId": "api_v2_allauth_browser_v1_auth_sessions_get" }, "delete": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "End one or more sessions", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/EndSessions" }, "responses": { "200": { "$ref": "#/components/responses/Sessions" }, "401": { "$ref": "#/components/responses/Authentication" } }, "operationId": "api_v2_allauth_browser_v1_auth_sessions_delete" } }, "/api/v2/allauth/app/v1/auth/sessions": { "get": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "List sessions", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "responses": { "200": { "$ref": "#/components/responses/Sessions" } }, "operationId": "api_v2_allauth_app_v1_auth_sessions_get" }, "delete": { "tags": [ "Authentication (Allauth Headless)" ], "summary": "End one or more sessions", "parameters": [ { "$ref": "#/components/parameters/Client" }, { "$ref": "#/components/parameters/SessionToken" } ], "requestBody": { "$ref": "#/components/requestBodies/EndSessions" }, "responses": { "200": { "$ref": "#/components/responses/Sessions" }, "401": { "$ref": "#/components/responses/Authentication" } }, "operationId": "api_v2_allauth_app_v1_auth_sessions_delete" } } }, "components": { "schemas": { "AccessLogResponse": { "type": "object", "properties": { "user": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/users/bob/" }, "date_created": { "type": "string", "format": "date-time" }, "username": { "type": "string" }, "metadata": { "type": "object", "properties": { "source": { "type": "string" }, "auth_type": { "type": "string" }, "ip_address": { "type": "string" }, "initial_user_uid": { "type": "string" }, "initial_user_username": { "type": "string" }, "authorized_app_name": { "type": "string" } } }, "user_uid": { "type": "string" }, "count": { "type": "integer" }, "action": { "type": "string" } }, "required": [ "action", "count", "date_created", "metadata", "user", "user_uid", "username" ] }, "ActionEnum": { "enum": [ "automatic_google_transcription", "automatic_google_translation", "manual_transcription", "manual_translation", "manual_qual", "automatic_bedrock_qual" ], "type": "string", "description": "* `automatic_google_transcription` - automatic_google_transcription\n* `automatic_google_translation` - automatic_google_translation\n* `manual_transcription` - manual_transcription\n* `manual_translation` - manual_translation\n* `manual_qual` - manual_qual\n* `automatic_bedrock_qual` - automatic_bedrock_qual" }, "ActionIdEnum": { "enum": [ "automatic_google_transcription", "automatic_google_translation" ], "type": "string", "description": "* `automatic_google_transcription` - automatic_google_transcription\n* `automatic_google_translation` - automatic_google_translation" }, "AdvancedFeatureCreateResponse": { "type": "object", "properties": { "question_xpath": { "type": "string" }, "action": { "$ref": "#/components/schemas/ActionEnum" }, "params": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/CreateResponseNLPActionParams" }, { "$ref": "#/components/schemas/CreateResponseManualQualActionParams" }, { "$ref": "#/components/schemas/CreateResponseAutomaticQualActionParams" } ] } }, "uid": { "type": "string" } }, "required": [ "action", "params", "question_xpath", "uid" ] }, "AdvancedFeaturePostRequest": { "type": "object", "properties": { "question_xpath": { "type": "string" }, "action": { "$ref": "#/components/schemas/ActionEnum" }, "params": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/RequestNLPActionParams" }, { "$ref": "#/components/schemas/RequestManualQualActionParams" }, { "$ref": "#/components/schemas/RequestAutomaticQualActionParams" } ] } } }, "required": [ "action", "params", "question_xpath" ] }, "AdvancedFeatureResponse": { "type": "object", "properties": { "question_xpath": { "type": "string" }, "action": { "$ref": "#/components/schemas/ActionEnum" }, "params": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/ResponseNLPActionParams" }, { "$ref": "#/components/schemas/ResponseManualQualActionParams" }, { "$ref": "#/components/schemas/ResponseAutomaticQualActionParams" } ] } }, "uid": { "type": "string" } }, "required": [ "action", "params", "question_xpath", "uid" ] }, "Asset": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/aBeA23YCYjkGTFvYVHuAyU/", "readOnly": true }, "owner": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/users/bob/", "readOnly": true }, "owner__username": { "type": "string", "description": "Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.", "readOnly": true }, "parent": { "type": [ "string", "null" ], "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/" }, "settings": { "type": "object", "properties": { "sector": { "type": [ "object", "null" ], "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "nullable": true }, "country": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } }, "nullable": true }, "description": { "type": "string" }, "collects_pii": { "type": [ "object", "null" ], "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "nullable": true }, "organization": { "type": [ "string", "null" ], "nullable": true }, "country_codes": { "type": "array", "items": { "type": "string" } }, "operational_purpose": { "type": [ "object", "null" ], "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "nullable": true } } }, "asset_type": { "$ref": "#/components/schemas/AssetTypeEnum" }, "files": { "type": "array", "items": { "type": "object", "properties": { "uid": { "type": "string" }, "url": { "type": "string" }, "asset": { "type": "string" }, "user": { "type": "string" }, "user__username": { "type": "string" }, "file_type": { "type": "string" }, "description": { "type": "string" }, "date_created": { "type": "string" }, "content": { "type": "string" }, "metadata": { "type": "object" } } }, "readOnly": true }, "summary": { "type": "object", "properties": { "geo": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "string" } }, "columns": { "type": "array", "items": { "type": "string" } }, "lock_all": { "type": "boolean" }, "lock_any": { "type": "boolean" }, "languages": { "type": "array", "items": { "type": "string" } }, "row_count": { "type": "integer" }, "name_quality": { "type": "object", "properties": { "ok": { "type": "integer" }, "bad": { "type": "integer" }, "good": { "type": "integer" }, "total": { "type": "integer" }, "firsts": { "type": "object", "properties": { "ok": { "type": "object", "properties": { "name": { "type": "string" }, "index": { "type": "integer" }, "label": { "type": "array", "items": { "type": "string" } } } }, "bad": { "type": "object", "properties": { "name": { "type": "string" }, "index": { "type": "integer" }, "label": { "type": "array", "items": { "type": "string" } } } } } } } }, "default_translation": { "type": [ "string", "null" ], "nullable": true }, "naming_conflicts": { "type": "array", "items": { "type": "string" } } }, "readOnly": true }, "date_created": { "type": "string", "format": "date-time" }, "date_modified": { "type": "string", "format": "date-time" }, "date_deployed": { "type": [ "string", "null" ], "format": "date-time" }, "version_id": { "type": [ "string", "null" ], "readOnly": true }, "version__content_hash": { "type": [ "string", "null" ], "readOnly": true }, "version_count": { "type": "integer", "readOnly": true }, "has_deployment": { "type": "boolean", "readOnly": true }, "deployed_version_id": { "type": [ "string", "null" ], "readOnly": true }, "deployed_versions": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": [ "string", "null" ], "nullable": true }, "previous": { "type": [ "string", "null" ], "nullable": true }, "results": { "type": "array", "items": { "type": "object", "properties": { "uid": { "type": "string" }, "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/aBeA23YCYjkGTFvYVHuAyU/versions/vBeA23YCYjkGTFvYVHuAyU/" }, "content_hash": { "type": "string" }, "date_deployed": { "type": "string", "format": "date-time" }, "date_modified": { "type": "string", "format": "date-time" } }, "required": [ "content_hash", "date_deployed", "date_modified", "uid", "url" ] } } }, "required": [ "count", "next", "previous", "results" ], "readOnly": true }, "deployment__links": { "type": "object", "readOnly": true }, "deployment__active": { "type": "boolean", "readOnly": true }, "deployment__data_download_links": { "type": "object", "properties": { "csv_legacy": { "type": "string" }, "csv": { "type": "string" }, "geojson": { "type": "string" }, "spss_labels": { "type": "string" }, "xls_legacy": { "type": "string" }, "xls": { "type": "string" }, "zip_legacy": { "type": "string" } }, "required": [ "csv", "csv_legacy", "xls", "xls_legacy", "zip_legacy" ], "readOnly": true }, "deployment__submission_count": { "type": "integer", "readOnly": true }, "deployment__last_submission_time": { "type": [ "string", "null" ], "format": "date-time", "readOnly": true }, "deployment__encrypted": { "type": "boolean", "readOnly": true }, "deployment__uuid": { "type": [ "string", "null" ], "readOnly": true }, "deployment_status": { "allOf": [ { "$ref": "#/components/schemas/AssetDeploymentStatusEnum" } ], "readOnly": true }, "report_styles": { "type": "object", "properties": { "default": { "type": "object", "properties": { "groupDataBy": { "type": "string" }, "report_type": { "type": "string" }, "report_colors": { "type": "array", "items": { "type": "string" } }, "translationIndex": { "type": "integer" }, "graphWidth": { "type": "integer" } } }, "specified": { "type": "object" }, "kuid_names": { "type": "object" } } }, "report_custom": { "type": "object" }, "advanced_features": { "type": "object", "properties": { "transcript": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string" } }, "languages": { "type": "array", "items": { "type": "string" } } } }, "translation": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string" } }, "languages": { "type": "array", "items": { "type": "string" } } } }, "qual": { "type": "object", "properties": { "qual_survey": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "uuid": { "type": "string" }, "options": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "xpath": { "type": "string" }, "scope": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "uuid": { "type": "string" }, "options": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "labels", "uuid" ] } } }, "required": [ "labels", "scope", "type", "xpath" ] } } } }, "_version": { "type": "string" } } }, "map_styles": { "type": "object", "properties": { "colorSet": { "type": "string" }, "querylimit": { "type": "string" }, "selectedQuestion": { "type": "string" } } }, "map_custom": { "type": "object" }, "content": { "type": "object", "properties": { "schema": { "type": "string" }, "survey": { "type": "array", "items": { "type": "object", "properties": { "$kuid": { "type": "string" }, "type": { "type": "string" }, "$xpath": { "type": "string" }, "$autoname": { "type": "string" }, "calculation": { "type": "string" }, "label": { "type": "array", "items": { "type": [ "string", "null" ], "nullable": true } }, "hint": { "type": "array", "items": { "type": [ "string", "null" ], "nullable": true } }, "name": { "type": "string" }, "required": { "type": "boolean" }, "appearance": { "type": "string" }, "parameters": { "type": "string" }, "kobo--matrix_list": { "type": "string" }, "kobo--rank-constraint-message": { "type": "string" }, "kobo--rank-items": { "type": "string" }, "kobo--score-choices": { "type": "string" }, "kobo--locking-profile": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "select_from_list_name": { "type": "string" }, "body::accept": { "type": "string" } }, "additionalProperties": true, "required": [ "$kuid", "type" ] } }, "choices": { "type": "array", "items": { "type": "object", "properties": { "$autovalue": { "type": "string" }, "$kuid": { "type": "string" }, "label": { "type": "array", "items": { "type": [ "string", "null" ], "nullable": true } }, "list_name": { "type": "string" }, "name": { "type": "string" }, "media::image": { "type": "array", "items": { "type": "string" } }, "$autoname": { "type": "string" } }, "additionalProperties": true, "required": [ "$autovalue", "$kuid", "list_name", "name" ] } }, "settings": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "id_string": { "type": "string" }, "style": { "type": "string" }, "form_id": { "type": "string" }, "title": { "type": "string" }, "kobo--lock_all": { "type": "boolean" }, "kobo--locking-profile": { "type": "string" }, "default_language": { "type": [ "string", "null" ], "nullable": true } } }, "translated": { "type": "array", "items": { "type": "string" } }, "translations": { "type": "array", "items": { "type": [ "string", "null" ], "nullable": true } }, "translations_0": { "type": [ "string", "null" ], "nullable": true }, "kobo--locking-profiles": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } } }, "downloads": { "type": "array", "items": { "type": "object", "properties": { "format": { "type": "string" }, "url": { "type": "string" } }, "required": [ "format", "url" ] }, "readOnly": true }, "embeds": { "type": "array", "items": { "type": "object", "properties": { "format": { "type": "string" }, "url": { "type": "string" } }, "required": [ "format", "url" ] }, "readOnly": true }, "analysis_form_json": { "type": "object", "properties": { "additional_fields": { "type": "array", "items": { "type": "object", "properties": { "language": { "type": "string" }, "source": { "type": "string" }, "type": { "type": "string", "enum": [ "transcript", "translation", "qualVerification", "qualSource", "qualInteger", "qualTags", "qualText", "qualNote", "qualAutoKeywordCount", "qualSelectMultiple", "qualSelectOne" ] }, "name": { "type": "string" }, "dtpath": { "type": "string" }, "label": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string" }, "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] } }, "required": [ "labels", "uuid" ] } } }, "required": [ "dtpath", "name", "source", "type" ] } } }, "required": [ "additional_fields" ], "readOnly": true }, "xform_link": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/aBeA23YCYjkGTFvYVHuAyU/xform/", "readOnly": true }, "hooks_link": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/aBeA23YCYjkGTFvYVHuAyU/hooks/", "readOnly": true }, "tag_string": { "type": "string" }, "uid": { "type": "string", "readOnly": true }, "kind": { "type": "string", "readOnly": true }, "xls_link": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/aBeA23YCYjkGTFvYVHuAyU.xls", "readOnly": true }, "name": { "type": "string", "maxLength": 255 }, "assignable_permissions": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "label": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "default": { "type": "string" }, "view_submissions": { "type": "string" }, "change_submissions": { "type": "string" }, "delete_submissions": { "type": "string" }, "validate_submissions": { "type": "string" } }, "required": [ "default" ] } ] } }, "required": [ "label", "url" ] }, "readOnly": true }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "user": { "type": "string" }, "permission": { "type": "string" }, "partial_permissions": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "filters": { "type": "array", "items": { "type": "object" } } } } }, "label": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "default": { "type": "string" }, "view_submissions": { "type": "string" }, "change_submissions": { "type": "string" }, "delete_submissions": { "type": "string" }, "validate_submissions": { "type": "string" } }, "required": [ "default" ] } ] } }, "required": [ "permission", "url", "user" ] }, "readOnly": true }, "effective_permissions": { "type": "array", "items": { "type": "object", "properties": { "codename": { "type": "string" } } }, "readOnly": true }, "exports": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/aBeA23YCYjkGTFvYVHuAyU/exports/", "readOnly": true }, "export_settings": { "type": "array", "items": { "$ref": "#/components/schemas/AssetExportSettings" }, "readOnly": true }, "data": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/aBeA23YCYjkGTFvYVHuAyU/data/", "readOnly": true }, "children": { "type": "object", "properties": { "count": { "type": "integer" } }, "readOnly": true }, "subscribers_count": { "type": "integer", "readOnly": true }, "status": { "type": "string", "readOnly": true }, "access_types": { "type": [ "array", "null", "null" ], "items": { "type": "string" }, "readOnly": true }, "data_sharing": { "type": "object" }, "paired_data": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/aBeA23YCYjkGTFvYVHuAyU/paired-data/", "readOnly": true }, "project_ownership": { "type": [ "object", "null" ], "additionalProperties": {}, "readOnly": true }, "owner_label": { "type": "string", "readOnly": true }, "last_modified_by": { "type": [ "string", "null" ], "readOnly": true }, "created_by": { "type": [ "string", "null" ], "readOnly": true } }, "required": [ "access_types", "analysis_form_json", "asset_type", "assignable_permissions", "children", "created_by", "data", "deployed_version_id", "deployed_versions", "deployment__active", "deployment__data_download_links", "deployment__encrypted", "deployment__last_submission_time", "deployment__links", "deployment__submission_count", "deployment__uuid", "deployment_status", "downloads", "effective_permissions", "embeds", "export_settings", "exports", "files", "has_deployment", "hooks_link", "kind", "last_modified_by", "owner", "owner__username", "owner_label", "paired_data", "permissions", "project_ownership", "status", "subscribers_count", "summary", "uid", "url", "version__content_hash", "version_count", "version_id", "xform_link", "xls_link" ] }, "AssetAttachmentAudioDurationItem": { "type": "object", "properties": { "uid": { "type": "string" }, "seconds": { "type": [ "integer", "null" ] } }, "required": [ "seconds", "uid" ] }, "AssetAttachmentAudioDurationRequest": { "type": "object", "properties": { "attachment_uids": { "type": "array", "items": { "type": "string" }, "description": "List of attachment UIDs whose audio duration to retrieve" } }, "required": [ "attachment_uids" ] }, "AssetAttachmentAudioDurationResponse": { "type": "object", "properties": { "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/AssetAttachmentAudioDurationItem" } }, "total": { "type": "integer" } }, "required": [ "attachments", "total" ] }, "AssetBulkRequest": { "oneOf": [ { "$ref": "#/components/schemas/AssetBulkRequestWithUids" }, { "$ref": "#/components/schemas/AssetBulkRequestWithConfirm" } ] }, "AssetBulkRequestWithConfirm": { "type": "object", "properties": { "confirm": { "type": "boolean" }, "action": { "type": "string" } }, "required": [ "action", "confirm" ] }, "AssetBulkRequestWithUids": { "type": "object", "properties": { "asset_uids": { "type": "object", "properties": { "asset_uids": { "type": "array", "items": { "type": "object" } } } }, "action": { "type": "string" } }, "required": [ "action", "asset_uids" ] }, "AssetBulkResponse": { "type": "object", "properties": { "detail": { "type": "string" } }, "required": [ "detail" ] }, "AssetCountResponse": { "type": "object", "properties": { "daily_submission_count": { "type": "object", "properties": { "2020-10-20": { "type": "integer" } } }, "total_submission_count": { "type": "integer" } }, "required": [ "daily_submission_count", "total_submission_count" ] }, "AssetCreateRequest": { "oneOf": [ { "$ref": "#/components/schemas/AssetCreateRequestClone" }, { "$ref": "#/components/schemas/AssetCreateRequestSettings" } ] }, "AssetCreateRequestClone": { "type": "object", "properties": { "name": { "type": "string" }, "clone_from": { "type": "string" }, "asset_type": { "type": "string" } }, "required": [ "asset_type", "clone_from", "name" ] }, "AssetCreateRequestSettings": { "type": "object", "properties": { "name": { "type": "string" }, "settings": { "type": "object", "properties": { "description": { "type": "string" }, "sector": { "type": "string" }, "country": { "type": "string" }, "share-metadata": { "type": "boolean" } } }, "asset_type": { "type": "string" } }, "required": [ "asset_type", "name", "settings" ] }, "AssetDeploymentStatusEnum": { "enum": [ "archived", "deployed", "draft", "-" ], "type": "string", "description": "* `archived` - Archived\n* `deployed` - Deployed\n* `draft` - Draft\n* `-` - -" }, "AssetExportSettings": { "type": "object", "properties": { "uid": { "type": "string", "readOnly": true }, "url": { "type": "string", "readOnly": true }, "data_url_csv": { "type": "string", "readOnly": true }, "data_url_xlsx": { "type": "string", "readOnly": true }, "name": { "type": "string" }, "date_modified": { "type": "string", "format": "date-time", "readOnly": true }, "export_settings": { "type": "object", "additionalProperties": {} } }, "required": [ "data_url_csv", "data_url_xlsx", "date_modified", "export_settings", "name", "uid", "url" ] }, "AssetListCount": { "type": "object", "properties": { "deployed_count": { "type": "integer", "readOnly": true }, "archived_count": { "type": "integer", "readOnly": true }, "draft_count": { "type": "integer", "readOnly": true } }, "required": [ "archived_count", "deployed_count", "draft_count" ] }, "AssetMetadataResponse": { "type": "object", "properties": { "languages": { "type": "array", "items": { "type": "string" } }, "countries": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "sectors": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "organizations": { "type": "array", "items": { "type": "string" } } }, "required": [ "countries", "languages", "organizations", "sectors" ] }, "AssetMinimalList": { "type": "object", "description": "Lightweight serializer returning only uid, name and deployment_status.\nUsed by the /api/v2/assets/minimal-list/ endpoint and its org/project-view variants.", "properties": { "uid": { "type": "string", "maxLength": 22 }, "name": { "type": "string", "readOnly": true }, "deployment_status": { "allOf": [ { "$ref": "#/components/schemas/AssetDeploymentStatusEnum" } ], "readOnly": true } }, "required": [ "deployment_status", "name", "uid" ] }, "AssetPatchRequestDataSharingFields": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "fields": { "type": "array", "items": { "type": "string" } } }, "required": [ "enabled", "fields" ] }, "AssetSnapshotCreateRequest": { "oneOf": [ { "type": "object", "properties": { "asset": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/" }, "details": { "type": "object", "properties": { "status": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } }, "required": [ "asset", "details" ] }, { "type": "object", "properties": { "source": { "type": "object", "properties": { "schema": { "type": "string" }, "survey": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } } }, "settings": { "type": "object", "properties": { "form_title": { "type": "string" } } }, "translated": { "type": "array", "items": { "type": "string" } }, "translation": { "type": "array", "items": { "type": "string" } } } }, "details": { "type": "object", "properties": { "status": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } }, "required": [ "details", "source" ] } ] }, "AssetSnapshotResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/asset_snapshots/sEMPghTguZsxj4rn4s9dvS/" }, "uid": { "type": "string" }, "owner": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/users/bob/" }, "date_created": { "type": "string", "format": "date-time" }, "xml": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/asset_snapshots/sEMPghTguZsxj4rn4s9dvS/" }, "enketopreviewlink": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/asset_snapshots/sEMPghTguZsxj4rn4s9dvS/preview/" }, "asset": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/" }, "asset_version_id": { "type": "string" }, "details": { "type": "object", "properties": { "status": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "source": { "type": "object", "properties": { "schema": { "type": "string" }, "survey": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } } }, "settings": { "type": "object", "properties": { "form_title": { "type": "string" } } }, "translated": { "type": "array", "items": { "type": "string" } }, "translation": { "type": "array", "items": { "type": "string" } } } } }, "required": [ "asset", "asset_version_id", "date_created", "details", "enketopreviewlink", "owner", "source", "uid", "url", "xml" ] }, "AssetSubscriptionRequest": { "type": "object", "properties": { "asset": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/" } }, "required": [ "asset" ] }, "AssetSubscriptionResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/asset_subscription/sEMPghTguZsxj4rn4s9dvS/" }, "asset": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/" }, "uid": { "type": "string" } }, "required": [ "asset", "uid", "url" ] }, "AssetTypeEnum": { "enum": [ "text", "empty", "question", "block", "survey", "template", "collection" ], "type": "string", "description": "* `text` - text\n* `empty` - empty\n* `question` - question\n* `block` - block\n* `survey` - survey\n* `template` - template\n* `collection` - collection" }, "AssetUsageResponse": { "type": "object", "properties": { "asset": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/" }, "asset__name": { "type": "string" }, "nlp_usage_current_period": { "type": "object", "properties": { "total_nlp_asr_seconds": { "type": "integer" }, "total_nlp_mt_characters": { "type": "integer" }, "total_nlp_llm_requests": { "type": "integer" } }, "required": [ "total_nlp_asr_seconds", "total_nlp_llm_requests", "total_nlp_mt_characters" ] }, "nlp_usage_all_time": { "type": "object", "properties": { "total_nlp_asr_seconds": { "type": "integer" }, "total_nlp_mt_characters": { "type": "integer" }, "total_nlp_llm_requests": { "type": "integer" } }, "required": [ "total_nlp_asr_seconds", "total_nlp_llm_requests", "total_nlp_mt_characters" ] }, "storage_bytes": { "type": "integer" }, "submission_count_current_period": { "type": "integer" }, "submission_count_all_time": { "type": "integer" } }, "required": [ "asset", "asset__name", "nlp_usage_all_time", "nlp_usage_current_period", "storage_bytes", "submission_count_all_time", "submission_count_current_period" ] }, "AssetValidContentResponse": { "type": "object", "properties": { "kind": { "type": "string" }, "uid": { "type": "string", "default": "akJTPb4JLVFqXMqYhKiPXZ" }, "data": { "type": "object", "properties": { "schema": { "type": "string" }, "survey": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "$kuid": { "type": "string" }, "$xpath": { "type": "string" }, "$autoname": { "type": "string" } } } }, "settings": { "type": "object" }, "translated": { "type": "array", "items": { "type": "string" } }, "translations": { "type": "array", "items": { "type": "string" } } } } }, "required": [ "data", "kind" ] }, "AuditLogResponse": { "type": "object", "properties": { "app_label": { "type": "string" }, "model_name": { "type": "string" }, "user": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/users/bob/" }, "user_uid": { "type": "string" }, "username": { "type": "string" }, "action": { "type": "string" }, "metadata": { "type": "object", "properties": { "source": { "type": "string" }, "settings": { "type": "object", "properties": { "sector": { "type": "object", "properties": { "new": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } }, "old": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } } } }, "country": { "type": "object", "properties": { "added": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } }, "removed": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } } } }, "description": { "type": "object", "properties": { "new": { "type": "string" }, "old": { "type": "string" } } }, "country_codes": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array", "items": { "type": "string" } } } }, "data-table": { "type": "object", "properties": { "new": { "type": "object" }, "old": { "type": "object" } } } } }, "asset_uid": { "type": "string" }, "auth_type": { "type": "string" }, "ip_address": { "type": "string" }, "log_subtype": { "type": "string" }, "project_owner": { "type": "string" }, "latest_version_uid": { "type": "string" }, "asset-files": { "type": "object", "properties": { "uid": { "type": "string" }, "filename": { "type": "string" }, "md5_hash": { "type": "string" }, "download_url": { "type": "string" } } }, "permissions": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array", "items": { "type": "string" } }, "username": { "type": "string" } } }, "latest_deployed_version_uid": { "type": "string" }, "submission": { "type": "object", "properties": { "root_uuid": { "type": "string" }, "submitted_by": { "type": "string" } } }, "hook": { "type": "object", "properties": { "uid": { "type": "string" }, "active": { "type": "boolean" }, "endpoint": { "type": "boolean" } } }, "bulk_action": { "type": "object", "properties": { "uid": { "type": "string" }, "action_id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "question_xpath": { "type": "string" }, "params": { "type": "object" }, "created_by": { "type": "string" }, "cancelled_by": { "type": "string" }, "total_count": { "type": "integer" }, "processed_count": { "type": "integer" }, "completed_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "cancelled_count": { "type": "integer" } } }, "name": { "type": "object", "properties": { "new": { "type": "string" }, "old": { "type": "string" } } }, "shared_fields": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array", "items": { "type": "string" } } } } } }, "date_created": { "type": "string", "format": "date-time" }, "log_type": { "type": "string" } }, "required": [ "action", "app_label", "date_created", "log_type", "metadata", "model_name", "user", "user_uid", "username" ] }, "AuthConfiguration": { "type": "object", "description": "Server branding and behaviour for the sign-in and account creation screens", "properties": { "theme": { "allOf": [ { "$ref": "#/components/schemas/AuthThemeEnum" } ], "description": "Appearance of everything outside the sign-in container. `custom` whenever a login background image has been uploaded, `default` otherwise\n\n* `default` - Default\n* `custom` - Customizable" }, "background_image_url": { "type": [ "string", "null" ], "description": "Relative URL of the login background image, or `null` when none has been uploaded" }, "show_kobotoolbox_logo": { "type": "boolean", "description": "Whether to display the KoboToolbox logo outside the container" }, "logo_url": { "type": [ "string", "null" ], "description": "Relative URL of the logo shown inside the container, or `null` when none has been uploaded" }, "supporting_image_url": { "type": [ "string", "null" ], "description": "Relative URL of the image displayed alongside the account creation form, or `null` when none has been uploaded" }, "supporting_text": { "type": "string", "description": "Rendered HTML displayed alongside the account creation form, localized for the request language. Empty when unset" }, "allow_login_with_username": { "type": "boolean", "description": "Whether this server accepts a username at sign-in. Reflects the login methods the server is configured with, so the sign-in form never offers a credential the server would reject" } }, "required": [ "allow_login_with_username", "background_image_url", "logo_url", "show_kobotoolbox_logo", "supporting_image_url", "supporting_text", "theme" ] }, "AuthLevelEnum": { "enum": [ "no_auth", "basic_auth" ], "type": "string", "description": "* `no_auth` - no_auth\n* `basic_auth` - basic_auth" }, "AuthThemeEnum": { "enum": [ "default", "custom" ], "type": "string", "description": "* `default` - Default\n* `custom` - Customizable" }, "BaseProduct": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 255 }, "name": { "type": "string", "description": "The product's name, meant to be displayable to the customer. Applicable to both `service` and `good` types.", "maxLength": 5000 }, "description": { "type": [ "string", "null" ], "description": "A description of this object." }, "type": { "allOf": [ { "$ref": "#/components/schemas/StripeProductType" } ], "description": "The type of the product. The product is either of type `good`, which is eligible for use with Orders and SKUs, or `service`, which is eligible for use with Subscriptions and Plans.\n\n* `good` - Good\n* `service` - Service" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "readOnly": true } }, "required": [ "id", "metadata", "name", "type" ] }, "BlankEnum": { "enum": [ "" ] }, "BulkAcceptRequest": { "type": "object", "properties": { "submission_uids": { "type": "array", "items": { "type": "string" } }, "question_xpath": { "type": "string" }, "action_id": { "$ref": "#/components/schemas/ActionIdEnum" }, "language": { "type": "string", "description": "Required for translation actions." }, "operation": { "allOf": [ { "$ref": "#/components/schemas/OperationEnum" } ], "description": "The operation to apply to the supplement data.\n\n* `accept` - accept" } }, "required": [ "action_id", "operation", "question_xpath", "submission_uids" ] }, "BulkAcceptResponse": { "type": "object", "properties": { "accepted_count": { "type": "integer", "minimum": 0, "description": "Number of submission records that were accepted." } }, "required": [ "accepted_count" ] }, "BulkActionCreateRequest": { "type": "object", "properties": { "action_id": { "$ref": "#/components/schemas/ActionIdEnum" }, "question_xpath": { "type": "string" }, "submission_uuids": { "type": "array", "items": { "type": "string" } }, "params": { "$ref": "#/components/schemas/BulkActionParamsRequest" } }, "required": [ "action_id", "params", "question_xpath", "submission_uuids" ] }, "BulkActionCreateResponse": { "type": "object", "properties": { "uid": { "type": "string" }, "status": { "$ref": "#/components/schemas/BulkActionResponseStatusEnum" }, "action_id": { "$ref": "#/components/schemas/ActionIdEnum" }, "question_xpath": { "type": "string" }, "submission_uuids": { "type": "array", "items": { "type": "string" } }, "submission_statuses": { "type": "array", "items": { "$ref": "#/components/schemas/BulkActionSubmissionStatusResponse" } }, "params": { "$ref": "#/components/schemas/BulkActionParamsResponse" }, "progress": { "type": "integer", "maximum": 100, "minimum": 0 }, "created_by": { "$ref": "#/components/schemas/BulkActionUserResponse" }, "date_created": { "type": "string", "format": "date-time" }, "date_modified": { "type": "string", "format": "date-time" }, "cancelled_by": { "oneOf": [ { "$ref": "#/components/schemas/BulkActionUserResponse" }, { "type": "null" } ] }, "skipped_uuids": { "type": "array", "items": { "type": "string" } } }, "required": [ "action_id", "created_by", "date_created", "date_modified", "params", "progress", "question_xpath", "skipped_uuids", "status", "submission_statuses", "submission_uuids", "uid" ] }, "BulkActionListResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": [ "string", "null" ] }, "previous": { "type": [ "string", "null" ] }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BulkActionResponse" } } }, "required": [ "count", "results" ] }, "BulkActionParamsRequest": { "type": "object", "properties": { "language": { "type": "string" }, "locale": { "type": "string" } }, "required": [ "language" ] }, "BulkActionParamsResponse": { "type": "object", "properties": { "language": { "type": "string" }, "locale": { "type": "string" } }, "required": [ "language" ] }, "BulkActionPatchRequestStatusEnum": { "enum": [ "cancelled" ], "type": "string", "description": "* `cancelled` - cancelled" }, "BulkActionResponse": { "type": "object", "properties": { "uid": { "type": "string" }, "status": { "$ref": "#/components/schemas/BulkActionResponseStatusEnum" }, "action_id": { "$ref": "#/components/schemas/ActionIdEnum" }, "question_xpath": { "type": "string" }, "submission_uuids": { "type": "array", "items": { "type": "string" } }, "submission_statuses": { "type": "array", "items": { "$ref": "#/components/schemas/BulkActionSubmissionStatusResponse" } }, "params": { "$ref": "#/components/schemas/BulkActionParamsResponse" }, "progress": { "type": "integer", "maximum": 100, "minimum": 0 }, "created_by": { "$ref": "#/components/schemas/BulkActionUserResponse" }, "date_created": { "type": "string", "format": "date-time" }, "date_modified": { "type": "string", "format": "date-time" }, "cancelled_by": { "oneOf": [ { "$ref": "#/components/schemas/BulkActionUserResponse" }, { "type": "null" } ] } }, "required": [ "action_id", "created_by", "date_created", "date_modified", "params", "progress", "question_xpath", "status", "submission_statuses", "submission_uuids", "uid" ] }, "BulkActionResponseStatusEnum": { "enum": [ "pending", "in_progress", "complete", "cancelled" ], "type": "string", "description": "* `pending` - pending\n* `in_progress` - in_progress\n* `complete` - complete\n* `cancelled` - cancelled" }, "BulkActionSubmissionStatusResponse": { "type": "object", "properties": { "uuid": { "type": "string" }, "status": { "$ref": "#/components/schemas/BulkActionSubmissionStatusResponseStatusEnum" }, "error": { "type": [ "string", "null" ] } }, "required": [ "error", "status", "uuid" ] }, "BulkActionSubmissionStatusResponseStatusEnum": { "enum": [ "pending", "in_progress", "complete", "cancelled", "failed" ], "type": "string", "description": "* `pending` - pending\n* `in_progress` - in_progress\n* `complete` - complete\n* `cancelled` - cancelled\n* `failed` - failed" }, "BulkActionUserResponse": { "type": "object", "properties": { "username": { "type": "string" } }, "required": [ "username" ] }, "ChangePlan": { "type": "object", "properties": { "price_id": { "type": "string" }, "subscription_id": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1, "default": 1 } }, "required": [ "price_id", "subscription_id" ] }, "CheckoutLink": { "type": "object", "properties": { "price_id": { "type": "string" }, "organization_id": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1, "default": 1 } }, "required": [ "price_id" ] }, "CollectionMethodEnum": { "enum": [ "charge_automatically", "send_invoice" ], "type": "string", "description": "* `charge_automatically` - Charge automatically\n* `send_invoice` - Send invoice" }, "ContentResponse": { "type": "object", "properties": { "kind": { "type": "string" }, "uid": { "type": "string", "default": "akJTPb4JLVFqXMqYhKiPXZ" }, "data": { "type": "object", "properties": { "survey": { "type": "array", "items": { "type": "object" } }, "settings": { "type": "object" } } } }, "required": [ "data", "kind" ] }, "CreateFilePayload": { "oneOf": [ { "$ref": "#/components/schemas/CreateFilePayloadBinary" }, { "$ref": "#/components/schemas/CreateFilePayloadBase64" }, { "$ref": "#/components/schemas/CreateFilePayloadURL" } ] }, "CreateFilePayloadBase64": { "type": "object", "properties": { "description": { "type": "string" }, "file_type": { "type": "string" }, "base64Encoded": { "type": "string" }, "metadata": { "type": "object", "required": [ "filename" ], "properties": { "filename": { "type": "string" } } } }, "required": [ "base64Encoded", "description", "file_type", "metadata" ] }, "CreateFilePayloadBinary": { "type": "object", "properties": { "description": { "type": "string" }, "file_type": { "type": "string" }, "content": { "type": "string" } }, "required": [ "content", "description", "file_type" ] }, "CreateFilePayloadURL": { "type": "object", "properties": { "description": { "type": "string" }, "file_type": { "type": "string" }, "metadata": { "type": "object", "required": [ "redirect_url" ], "properties": { "redirect_url": { "type": "string", "format": "uri" } } } }, "required": [ "description", "file_type", "metadata" ] }, "CreateResponseAutomaticQualActionParams": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } }, "additionalProperties": false, "required": [ "uuid" ] }, "CreateResponseManualQualActionParams": { "anyOf": [ { "$ref": "#/components/schemas/CreateResponseQualSimpleQuestionParams" }, { "$ref": "#/components/schemas/CreateResponseQualSelectQuestionParams" } ] }, "CreateResponseNLPActionParams": { "type": "object", "additionalProperties": false, "properties": { "language": { "type": "string" } }, "required": [ "language" ] }, "CreateResponseQualSelectQuestionParams": { "type": "object", "additionalProperties": false, "properties": { "uuid": { "type": "string", "format": "uuid" }, "type": { "$ref": "#/components/schemas/QualSelectQuestionParamsTypeEnum" }, "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "choices": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "uuid": { "type": "string", "format": "uuid" }, "hint": { "type": "object", "additionalProperties": false, "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "required": "labels" } }, "required": [ "labels", "uuid" ] } }, "hint": { "type": "object", "additionalProperties": false, "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "required": "labels" } }, "required": [ "uuid", "type", "labels", "choices" ] }, "CreateResponseQualSimpleQuestionParams": { "type": "object", "additionalProperties": false, "properties": { "uuid": { "type": "string", "format": "uuid" }, "type": { "$ref": "#/components/schemas/QualSimpleQuestionParamsTypeEnum" }, "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "hint": { "type": "object", "additionalProperties": false, "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "required": "labels" } }, "required": [ "uuid", "type", "labels" ] }, "CustomAssetUsage": { "type": "object", "properties": { "asset": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/organizations/orgzeph7Ub8tVmJ82JBbH96n/", "readOnly": true }, "asset__name": { "type": "string", "readOnly": true }, "nlp_usage_current_period": { "allOf": [ { "$ref": "#/components/schemas/NlpUsage" } ], "readOnly": true }, "nlp_usage_all_time": { "allOf": [ { "$ref": "#/components/schemas/NlpUsage" } ], "readOnly": true }, "storage_bytes": { "type": "integer", "readOnly": true }, "submission_count_current_period": { "type": "integer", "readOnly": true }, "submission_count_all_time": { "type": "integer", "readOnly": true }, "deployment_status": { "allOf": [ { "$ref": "#/components/schemas/CustomAssetUsageDeploymentStatusEnum" } ], "readOnly": true } }, "required": [ "asset", "asset__name", "deployment_status", "nlp_usage_all_time", "nlp_usage_current_period", "storage_bytes", "submission_count_all_time", "submission_count_current_period" ] }, "CustomAssetUsageDeploymentStatusEnum": { "enum": [ "archived", "deployed", "draft" ], "type": "string", "description": "* `archived` - archived\n* `deployed` - deployed\n* `draft` - draft" }, "CustomerPortal": { "type": "object", "properties": { "organization_id": { "type": "string" }, "price_id": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1, "default": 1 } }, "required": [ "organization_id" ] }, "CustomerPortalPostResponse": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] }, "DataBulkDelete": { "type": "object", "properties": { "payload": { "type": "array", "items": { "type": "integer" } } }, "required": [ "payload" ] }, "DataBulkUpdateResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "successes": { "type": "integer" }, "failures": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string" }, "status_code": { "type": "integer" }, "message": { "type": "string" } } } } }, "required": [ "count", "failures", "results", "successes" ] }, "DataResponse": { "type": "object", "properties": { "_id": { "type": "integer", "title": " id" }, "formhub/uuid": { "type": "string" }, "__version__": { "type": "string", "title": " version " }, "meta/instanceID": { "type": "string" }, "meta/rootUuid": { "type": "string" }, "meta/deprecatedID": { "type": "string" }, "meta/formVersions": { "type": "string" }, "_xform_id_string": { "type": "string", "title": " xform id string" }, "_uuid": { "type": "string", "title": " uuid" }, "_attachments": { "type": "array", "items": { "type": "object", "properties": { "download_url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/aTPPUDScaFZkvBzd8FyK4Q/data/18/attachments/1" }, "download_large_url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/aTPPUDScaFZkvBzd8FyK4Q/data/18/attachments/attWNZNwhXK6HDYVkZJSn9jy/large/" }, "download_medium_url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/aTPPUDScaFZkvBzd8FyK4Q/data/18/attachments/attWNZNwhXK6HDYVkZJSn9jy/medium/" }, "download_small_url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/aTPPUDScaFZkvBzd8FyK4Q/data/18/attachments/attWNZNwhXK6HDYVkZJSn9jy/small/" }, "mimetype": { "type": "string", "example": "image/png" }, "media_file_basename": { "type": "string" }, "filename": { "type": "string" }, "uid": { "type": "string" }, "question_xpath": { "type": "string" }, "is_deleted": { "type": "boolean" } }, "required": [ "download_url", "filename", "media_file_basename", "mimetype", "question_xpath", "uid" ], "additional_properties": false }, "title": " attachments" }, "_status": { "type": "string", "title": " status" }, "_geolocation": { "type": "array", "items": { "type": [ "number", "null" ] }, "minItems": 2, "maxItems": 2, "title": " geolocation" }, "_submission_time": { "type": "string", "format": "date-time", "title": " submission time" }, "_validation_status": { "oneOf": [ { "$ref": "#/components/schemas/DataValidationStatus" }, { "type": "object", "maxProperties": 0 } ], "title": " validation status" }, "_submitted_by": { "type": "string", "title": " submitted by" }, "_supplementalDetails": { "oneOf": [ { "type": "object", "description": "Manual transcription supplemental details", "additionalProperties": { "type": "object", "properties": { "manual_transcription": { "$ref": "#/components/schemas/SupplementalDataManualTranscription" } }, "required": [ "manual_transcription" ] } }, { "type": "object", "description": "Manual translation supplemental details", "additionalProperties": { "type": "object", "properties": { "manual_translation": { "$ref": "#/components/schemas/SupplementalDataManualTranslation" } }, "required": [ "manual_translation" ] } }, { "type": "object", "description": "Automatic transcription supplemental details", "additionalProperties": { "type": "object", "properties": { "automatic_google_transcription": { "$ref": "#/components/schemas/SupplementalDataAutomaticTranscription" } }, "required": [ "automatic_google_transcription" ] } }, { "type": "object", "description": "Automatic translation supplemental details", "additionalProperties": { "type": "object", "properties": { "automatic_google_translation": { "$ref": "#/components/schemas/SupplementalDataAutomaticTranslation" } }, "required": [ "automatic_google_translation" ] } }, { "type": "object", "description": "Manual qualitative supplemental details", "additionalProperties": { "type": "object", "properties": { "manual_qual": { "$ref": "#/components/schemas/SupplementalDataManualQual" } }, "required": [ "manual_qual" ] } }, { "type": "object", "description": "Automatic qualitative supplemental details", "additionalProperties": { "type": "object", "properties": { "automatic_bedrock_qual": { "$ref": "#/components/schemas/SupplementalDataAutomaticQual" } }, "required": [ "automatic_bedrock_qual" ] } }, { "type": "null" } ], "description": "Action-specific supplemental data attached to this submission. Structure varies by action type (transcription, translation, qual). Top-level keys are question XPaths, values are action objects.", "title": " supplementaldetails" } }, "required": [ "__version__", "_attachments", "_geolocation", "_id", "_status", "_submission_time", "_submitted_by", "_uuid", "_validation_status", "_xform_id_string", "meta/instanceID", "meta/rootUuid" ] }, "DataResponseXML": { "type": "object", "properties": { "formhub": { "$ref": "#/components/schemas/DataResponseXMLFormhub" }, "__version__": { "type": "string", "title": " version " }, "meta": { "$ref": "#/components/schemas/DataResponseXMLMeta" }, "_geolocation": { "allOf": [ { "$ref": "#/components/schemas/DataResponseXMLGeoLocation" } ], "title": " geolocation" } }, "required": [ "__version__", "_geolocation", "meta" ] }, "DataResponseXMLFormhub": { "type": "object", "properties": { "uuid": { "type": "string" } }, "required": [ "uuid" ] }, "DataResponseXMLGeoLocation": { "type": "object", "properties": { "latitude": { "type": "number", "format": "double" }, "longitude": { "type": "number", "format": "double" } }, "required": [ "latitude", "longitude" ] }, "DataResponseXMLMeta": { "type": "object", "properties": { "instanceID": { "type": "string" }, "deprecatedID": { "type": "string" }, "formVersions": { "type": "string" } }, "required": [ "instanceID" ] }, "DataStatusesUpdate": { "type": "object", "properties": { "detail": { "type": "string" } }, "required": [ "detail" ] }, "DataSupplementAutomaticQualDataIntegerResponse": { "type": "object", "additionalProperties": false, "oneOf": [ { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "value": { "type": "integer", "nullable": true }, "status": { "type": "string", "const": "complete" } }, "additionalProperties": false, "required": [ "status", "uuid", "value" ] }, { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string", "const": "failed" }, "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error", "status", "uuid" ] } ], "discriminator": { "propertyName": "status" } }, "DataSupplementAutomaticQualDataSelectMultipleResponse": { "type": "object", "additionalProperties": false, "oneOf": [ { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "value": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "status": { "type": "string", "const": "complete" } }, "additionalProperties": false, "required": [ "status", "uuid", "value" ] }, { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string", "const": "failed" }, "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error", "status", "uuid" ] } ], "discriminator": { "propertyName": "status" } }, "DataSupplementAutomaticQualDataSelectOneResponse": { "type": "object", "additionalProperties": false, "oneOf": [ { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "value": { "type": "string", "format": "uuid" }, "status": { "type": "string", "const": "complete" } }, "additionalProperties": false, "required": [ "status", "uuid", "value" ] }, { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string", "const": "failed" }, "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error", "status", "uuid" ] } ], "discriminator": { "propertyName": "status" } }, "DataSupplementAutomaticQualDataTextResponse": { "type": "object", "additionalProperties": false, "oneOf": [ { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "value": { "type": "string" }, "status": { "type": "string", "const": "complete" } }, "additionalProperties": false, "required": [ "status", "uuid", "value" ] }, { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string", "const": "failed" }, "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error", "status", "uuid" ] } ], "discriminator": { "propertyName": "status" } }, "DataSupplementManualQualDataInteger": { "type": "object", "additionalProperties": false, "properties": { "value": { "type": "integer", "nullable": true }, "uuid": { "type": "string", "format": "uuid" } }, "required": [ "uuid", "value" ] }, "DataSupplementManualQualDataSelectMultiple": { "type": "object", "additionalProperties": false, "properties": { "value": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "uuid": { "type": "string", "format": "uuid" } }, "required": [ "uuid", "value" ] }, "DataSupplementManualQualDataSelectOne": { "type": "object", "additionalProperties": false, "properties": { "value": { "type": "string", "format": "uuid" }, "uuid": { "type": "string", "format": "uuid" } }, "required": [ "uuid", "value" ] }, "DataSupplementManualQualDataTags": { "type": "object", "additionalProperties": false, "properties": { "value": { "type": "array", "items": { "type": "string" } }, "uuid": { "type": "string", "format": "uuid" } }, "required": [ "uuid", "value" ] }, "DataSupplementManualQualDataText": { "type": "object", "additionalProperties": false, "properties": { "value": { "type": "string" }, "uuid": { "type": "string", "format": "uuid" } }, "required": [ "uuid", "value" ] }, "DataSupplementResponse": { "type": "object", "properties": { "_version": { "type": "string", "example": "20250820" } }, "additionalProperties": { "$ref": "#/components/schemas/SupplementalDataResponseAction" }, "required": [ "_version" ], "patternProperties": { "^(?!_version$).*": { "$ref": "#/components/schemas/SupplementalDataResponseAction" } } }, "DataValidationStatus": { "type": "object", "properties": { "timestamp": { "type": "integer" }, "uid": { "$ref": "#/components/schemas/DataValidationStatusUidEnum" }, "by_whom": { "type": "string" }, "label": { "$ref": "#/components/schemas/DataValidationStatusLabelEnum" } }, "required": [ "timestamp", "uid", "label", "by_whom" ], "additionalProperties": false }, "DataValidationStatusLabelEnum": { "enum": [ "Not Approved", "Approved", "On Hold" ] }, "DataValidationStatusUidEnum": { "enum": [ "validation_status_not_approved", "validation_status_approved", "validation_status_on_hold" ] }, "DataValidationStatusUpdateResponse": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "uid": { "type": "string" }, "by_whom": { "type": "string" }, "label": { "type": "string" } }, "required": [ "by_whom", "label", "timestamp", "uid" ] }, "DeploymentCreateRequest": { "type": "object", "properties": { "active": { "type": "boolean" } }, "required": [ "active" ] }, "DeploymentResponse": { "type": "object", "properties": { "backend": { "type": "string" }, "active": { "type": "boolean" }, "version_id": { "type": "string" }, "asset": { "$ref": "#/components/schemas/Asset" } }, "required": [ "active", "asset", "backend", "version_id" ] }, "EmailAddress": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/Email" }, "primary": { "type": "boolean", "example": true }, "verified": { "type": "boolean", "example": false } }, "required": [ "email", "primary", "verified" ] }, "EmailConfirmationRequestPayload": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": [ "email" ] }, "EmailConfirmationRequestResponse": { "type": "object", "properties": { "detail": { "type": "string" } }, "required": [ "detail" ] }, "EmailReauthenticationRequiredResponse": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" }, "flows": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, "required": [ "code", "detail", "flows" ] }, "EmailRequestPayload": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "current_password": { "type": "string" }, "mfa_code": { "type": "string" } }, "required": [ "email" ] }, "EnketoEditResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/edit/iXUdUc3w?instance_id=1824b282-f729-4944-b799-7a805d4564e1&return_url=false" }, "version": { "type": "string" } }, "required": [ "url", "version" ] }, "EnketoViewResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/view/f93d2a488a2e35cedc336e84e1bd1edc?instance_id=1824b282-f729-4944-b799-7a805d4564e1&return_url=false" }, "version": { "type": "string" } }, "required": [ "url", "version" ] }, "EnvironmentResponse": { "type": "object", "properties": { "registration_open": { "type": "boolean", "description": "Whether users may create their own accounts" }, "terms_of_service_url": { "type": [ "string", "null" ] }, "privacy_policy_url": { "type": [ "string", "null" ] }, "source_code_url": { "type": [ "string", "null" ] }, "support_email": { "type": [ "string", "null" ] }, "support_url": { "type": [ "string", "null" ] }, "academy_url": { "type": [ "string", "null" ] }, "community_url": { "type": [ "string", "null" ] }, "frontend_min_retry_time": { "type": "integer" }, "frontend_max_retry_time": { "type": "integer" }, "use_team_label": { "type": "boolean" }, "usage_limit_enforcement": { "type": "boolean" }, "allow_self_account_deletion": { "type": "boolean" }, "project_history_log_lifespan": { "type": "integer" }, "sector_choices": { "type": "array", "items": { "type": "array", "items": { "type": "string" }, "maxItems": 2, "minItems": 2 }, "description": "A list of (value, label) tuples for sectors" }, "operational_purpose_choices": { "type": "array", "items": { "type": "array", "items": { "type": "string" }, "maxItems": 2, "minItems": 2 }, "description": "A list of (value, label) tuples for operational purposes" }, "country_choices": { "type": "array", "items": { "type": "array", "items": { "type": "string" }, "maxItems": 2, "minItems": 2 }, "description": "A list of (country_code, country_name) tuples" }, "interface_languages": { "type": "array", "items": { "type": "array", "items": { "type": "string" }, "maxItems": 2, "minItems": 2 }, "description": "A list of (language_code, language_name) tuples" }, "mfa_localized_help_text": { "type": "string", "description": "Markdown string for MFA help text" }, "mfa_enabled": { "type": "boolean" }, "mfa_code_length": { "type": "integer" }, "superuser_auth_enforcement": { "type": "boolean" }, "enable_password_entropy_meter": { "type": "boolean" }, "enable_custom_password_guidance_text": { "type": "boolean" }, "custom_password_localized_help_text": { "type": "string", "description": "Markdown string for custom password help text" }, "auth_configuration": { "$ref": "#/components/schemas/AuthConfiguration" }, "project_metadata_fields": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataField" } }, "extra_project_metadata_fields": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataField" } }, "user_metadata_fields": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataField" } }, "social_apps": { "type": "array", "items": { "$ref": "#/components/schemas/SocialApp" } }, "asr_mt_features_enabled": { "type": "boolean", "description": "Whether ASR and MT features are enabled for the current user" }, "submission_placeholder": { "type": "string", "description": "Placeholder text for submissions" }, "stripe_public_key": { "type": [ "string", "null" ] }, "terms_of_service__sitewidemessage__exists": { "type": "boolean", "description": "Indicates if a sitewide message for TOS exists" }, "open_rosa_server": { "type": "string", "format": "uri", "description": "The OpenRosa server URL (KC)" } }, "required": [ "academy_url", "allow_self_account_deletion", "asr_mt_features_enabled", "auth_configuration", "community_url", "country_choices", "custom_password_localized_help_text", "enable_custom_password_guidance_text", "enable_password_entropy_meter", "extra_project_metadata_fields", "frontend_max_retry_time", "frontend_min_retry_time", "interface_languages", "mfa_code_length", "mfa_enabled", "mfa_localized_help_text", "open_rosa_server", "operational_purpose_choices", "privacy_policy_url", "project_history_log_lifespan", "project_metadata_fields", "registration_open", "sector_choices", "social_apps", "source_code_url", "stripe_public_key", "submission_placeholder", "superuser_auth_enforcement", "support_email", "support_url", "terms_of_service__sitewidemessage__exists", "terms_of_service_url", "usage_limit_enforcement", "use_team_label", "user_metadata_fields" ] }, "ErrorDetail": { "type": "object", "properties": { "detail": { "type": "string" } }, "required": [ "detail" ] }, "ErrorValidation": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "ExportCreatePayload": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "string" } }, "fields_from_all_versions": { "type": "boolean" }, "group_sep": { "type": "string" }, "hierarchy_in_labels": { "type": "boolean" }, "include_media_url": { "type": "boolean" }, "lang": { "type": "string" }, "multiple_select": { "type": "string" }, "submissions_id": { "type": "array", "items": { "type": "integer" } }, "type": { "type": "string" }, "flatten": { "type": "boolean" }, "xls_types_as_text": { "type": "boolean" }, "query": { "type": "object", "properties": { "$and": { "type": "array", "items": { "type": "object", "properties": { "_submission_time": { "type": "object", "properties": { "$gte": { "type": "string", "format": "date" } } } } } } } } }, "required": [ "fields", "fields_from_all_versions", "flatten", "group_sep", "hierarchy_in_labels", "include_media_url", "lang", "multiple_select", "query", "submissions_id", "type", "xls_types_as_text" ] }, "ExportCreateResponse": { "type": "object", "properties": { "status": { "type": "string", "maxLength": 32 } }, "required": [ "status" ] }, "ExportHistoryResponse": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] }, "ExportListResponse": { "type": "object", "properties": { "uid": { "type": "string", "maxLength": 24 }, "status": { "type": "string", "maxLength": 32 }, "date_created": { "type": "string", "format": "date-time" } }, "required": [ "date_created", "status", "uid" ] }, "ExportResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/exports/eYeXfo2KjbSzXgWuKsJNPY/" }, "status": { "type": "string" }, "message": { "type": "object" }, "uid": { "type": "string" }, "date_created": { "type": "string", "format": "date-time" }, "last_submission_time": { "type": "string", "format": "date-time" }, "result": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/user/export/NEW PROJECT - all versions - False - 2025-01-01-01-01.csv" }, "data": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/" }, "group_sep": { "type": "string" }, "multiple_select": { "type": "string" }, "include_media_url": { "type": "boolean" }, "hierarchy_in_labels": { "type": "boolean" }, "processing_time_seconds": { "type": "number", "format": "float" }, "fields_from_all_versions": { "type": "boolean" } } } }, "required": [ "data", "date_created", "last_submission_time", "message", "result", "status", "uid", "url" ] }, "ExportSettingCreatePayload": { "type": "object", "properties": { "name": { "type": "string" }, "export_settings": { "type": "object", "properties": { "fields_from_all_versions": { "type": "boolean" }, "group_sep": { "type": "string" }, "hierarchy_in_labels": { "type": "boolean" }, "lang": { "type": "boolean" }, "multiple_select": { "type": "string" }, "types": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } }, "flatten": { "type": "boolean" }, "xls_types_as_text": { "type": "boolean" }, "include_media_url": { "type": "boolean" }, "submission_ids": { "type": "array", "items": { "type": "integer" } }, "query": { "type": "object", "properties": { "$and": { "type": "array", "items": { "type": "object", "properties": { "_submission_time": { "type": "object", "properties": { "$gte": { "type": "string", "format": "date" } } } } } } } } } } }, "required": [ "export_settings", "name" ] }, "ExportSettingResponse": { "type": "object", "properties": { "uid": { "type": "string" }, "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/export-settings/esMxJfzPhnWn6r2c3EKkuaV/" }, "data_url_csv": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/export-settings/esMxJfzPhnWn6r2c3EKkuaV/data.csv" }, "data_url_xlsx": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/export-settings/esMxJfzPhnWn6r2c3EKkuaV/data.xlsx" }, "name": { "type": "string" }, "date_modified": { "type": "string", "format": "date-time" }, "export_settings": { "type": "object", "properties": { "lang": { "type": "string" }, "type": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } }, "group_sep": { "type": "string" }, "multiple_select": { "type": "string" }, "include_media_url": { "type": "boolean" }, "xls_types_as_text": { "type": "boolean" }, "hierarchy_in_labels": { "type": "boolean" }, "fields_from_all_versions": { "type": "boolean" } } } }, "required": [ "data_url_csv", "data_url_xlsx", "date_modified", "export_settings", "name", "uid", "url" ] }, "ExportTypeEnum": { "enum": [ "xml", "json" ], "type": "string", "description": "* `xml` - xml\n* `json` - json" }, "ExternalResponse": { "type": "object", "properties": { "root": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "string" }, "field_value_1": { "type": "string" }, "field_value_2": { "type": "string" } } } } } } }, "required": [ "root" ] }, "FilesResponse": { "type": "object", "properties": { "uid": { "type": "string" }, "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/files/afSa8PqnoYe8vJqkrsGz3oN/" }, "asset": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/" }, "user": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/users/bob/" }, "user__username": { "type": "string" }, "file_type": { "type": "string" }, "description": { "type": "string" }, "date_created": { "type": "string", "format": "date-time" }, "content": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/files/afSa8PqnoYe8vJqkrsGz3oN/content/" }, "metadata": { "type": "object", "properties": { "hash": { "type": "string" }, "filename": { "type": "string" }, "mimetype": { "type": "string" } } } }, "required": [ "asset", "content", "date_created", "description", "file_type", "metadata", "uid", "url", "user", "user__username" ] }, "HashResponse": { "type": "object", "properties": { "hash": { "type": "string" } }, "required": [ "hash" ] }, "HistoryActionResponse": { "type": "object", "properties": { "actions": { "type": "array", "items": { "type": "string" } } }, "required": [ "actions" ] }, "HistoryListResponse": { "type": "object", "properties": { "user": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/users/bob/" }, "user_uid": { "type": "string" }, "username": { "type": "string" }, "action": { "type": "string" }, "metadata": { "type": "object", "properties": { "source": { "type": "string" }, "settings": { "type": "object", "properties": { "sector": { "type": "object", "properties": { "new": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } }, "old": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } } } }, "country": { "type": "object", "properties": { "added": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } }, "removed": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } } } }, "description": { "type": "object", "properties": { "new": { "type": "string" }, "old": { "type": "string" } } }, "country_codes": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array", "items": { "type": "string" } } } }, "data-table": { "type": "object", "properties": { "new": { "type": "object" }, "old": { "type": "object" } } } } }, "asset_uid": { "type": "string" }, "ip_address": { "type": "string" }, "log_subtype": { "type": "string" }, "project_owner": { "type": "string" }, "latest_version_uid": { "type": "string" }, "asset-files": { "type": "object", "properties": { "uid": { "type": "string" }, "filename": { "type": "string" }, "md5_hash": { "type": "string" }, "download_url": { "type": "string" } } }, "permissions": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array", "items": { "type": "string" } }, "username": { "type": "string" } } }, "latest_deployed_version_uid": { "type": "string" }, "submission": { "type": "object", "properties": { "root_uuid": { "type": "string" }, "submitted_by": { "type": "string" } } }, "hook": { "type": "object", "properties": { "uid": { "type": "string" }, "active": { "type": "boolean" }, "endpoint": { "type": "boolean" } } }, "bulk_action": { "type": "object", "properties": { "uid": { "type": "string" }, "action_id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "question_xpath": { "type": "string" }, "params": { "type": "object" }, "created_by": { "type": "string" }, "cancelled_by": { "type": "string" }, "total_count": { "type": "integer" }, "processed_count": { "type": "integer" }, "completed_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "cancelled_count": { "type": "integer" } } }, "name": { "type": "object", "properties": { "new": { "type": "string" }, "old": { "type": "string" } } }, "shared_fields": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array", "items": { "type": "string" } } } } } }, "date_created": { "type": "string", "format": "date-time" } }, "required": [ "action", "date_created", "metadata", "user", "user_uid", "username" ] }, "Hook": { "type": "object", "properties": { "active": { "type": "boolean" }, "asset": { "type": "integer", "readOnly": true }, "auth_level": { "$ref": "#/components/schemas/AuthLevelEnum" }, "date_modified": { "type": "string", "format": "date-time", "readOnly": true }, "email_notification": { "type": "boolean" }, "endpoint": { "type": "string", "maxLength": 500 }, "export_type": { "$ref": "#/components/schemas/ExportTypeEnum" }, "failed_count": { "type": "integer", "readOnly": true }, "logs_url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/hooks/hZzzeedWxQoFHgibsTCysv/logs/", "readOnly": true }, "name": { "type": "string", "maxLength": 255 }, "payload_template": { "type": [ "string", "null" ] }, "pending_count": { "type": "integer", "readOnly": true }, "settings": { "type": "object", "properties": { "password": { "type": "string" }, "username": { "type": "string" }, "custom_headers": { "type": "object", "properties": { "value_field": { "type": "string" }, "value_field_2": { "type": "string" } } } } }, "subset_fields": { "type": "array", "items": { "type": "string" } }, "success_count": { "type": "integer", "readOnly": true }, "uid": { "type": "string", "readOnly": true }, "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/", "readOnly": true } }, "required": [ "asset", "date_modified", "endpoint", "failed_count", "logs_url", "name", "pending_count", "success_count", "uid", "url" ] }, "HookLog": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/aTPPUDScaFZkvBzd8FyK4Q/hooks/hsw3Ec5vz7Lqg7TrwrxdaS/logs/hl8Ldv5m84SBpU5UB5J7QBD/", "readOnly": true }, "uid": { "type": "string", "readOnly": true }, "submission_id": { "type": "integer", "readOnly": true }, "tries": { "type": "integer", "readOnly": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/HookLogStatusEnum" } ], "readOnly": true }, "status_str": { "type": "string" }, "status_code": { "type": [ "integer", "null" ], "readOnly": true }, "message": { "type": "string", "readOnly": true }, "date_modified": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "date_modified", "message", "status", "status_code", "status_str", "submission_id", "tries", "uid", "url" ] }, "HookLogStatusEnum": { "enum": [ 0, 1, 3, 2 ], "type": "integer", "description": "* `0` - failed\n* `1` - pending\n* `3` - processing\n* `2` - success" }, "HookRetryResponse": { "type": "object", "properties": { "detail": { "type": "string" }, "pending_uids": { "type": "array", "items": { "type": "string" } } }, "required": [ "detail", "pending_uids" ] }, "ImportCreateRequest": { "type": "object", "properties": { "destination": { "type": [ "string", "null" ], "format": "uri" }, "url": { "type": [ "string", "null" ], "format": "uri" }, "name": { "type": [ "string", "null" ] }, "assetUid": { "type": [ "string", "null" ] }, "base64Encoded": { "type": [ "string", "null" ] }, "library": { "type": [ "boolean", "null" ] }, "desired_type": { "type": [ "string", "null" ] }, "totalFiles": { "type": [ "integer", "null" ] }, "file": { "type": [ "string", "null" ], "format": "binary" } } }, "ImportCreateResponse": { "type": "object", "properties": { "uid": { "type": "string" }, "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/imports/iYxVZhbZb6poxVpPqrd6eG/" }, "status": { "type": "string" } }, "required": [ "status", "uid", "url" ] }, "ImportResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/imports/iYxVZhbZb6poxVpPqrd6eG/" }, "status": { "type": "string" }, "messages": { "type": "object", "properties": { "updated": { "type": "array", "items": { "type": "object", "properties": { "uid": { "type": "string" }, "kind": { "type": "string" }, "summary": { "type": "object", "properties": { "geo": { "type": "boolean" }, "labels": { "type": "array", "items": { "type": "string" } }, "columns": { "type": "array", "items": { "type": "string" } }, "language": { "type": "array", "items": { "type": "string" } }, "row_count": { "type": "integer" }, "name_quality": { "type": "object", "properties": { "ok": { "type": "integer" }, "bad": { "type": "integer" }, "good": { "type": "integer" }, "total": { "type": "integer" }, "first": { "type": "object" } } }, "default_translation": { "type": "string" } } }, "owner__username": { "type": "string" } } } }, "audit-logs": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "asset_id": { "type": "integer" }, "new_name": { "type": "string" }, "old_name": { "type": "string" }, "asset_uid": { "type": "string" }, "ip_address": { "type": "string" }, "project_owner": { "type": "string" }, "latest_version_uid": { "type": "string" } } } }, "error": { "type": "string" }, "error_type": { "type": "string" } } }, "uid": { "type": "string" }, "date_created": { "type": "string", "format": "date-time" } }, "required": [ "date_created", "messages", "status", "uid", "url" ] }, "InviteCreatePayload": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/InviteeRoleEnum" }, "invitees": { "type": "array", "items": { "type": "string" } } }, "required": [ "invitees", "role" ] }, "InviteCreateResponse": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/organizations/orgR6zUBwMHop2mgGygtFd6c/invites/f3ba00b2-372b-4283-9d57-adbe7d5b1bf1/" }, "invited_by": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/users/bob/" }, "status": { "type": "string" }, "invitee_role": { "enum": [ "admin", "member" ], "type": "string", "description": "* `admin` - admin\n* `member` - member" }, "organization_name": { "type": "string" }, "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" }, "invitee": { "type": "string" } }, "required": [ "created", "invited_by", "invitee", "invitee_role", "modified", "organization_name", "status", "url" ] } }, "InviteResponse": { "type": "object", "properties": { "invitee_role": { "$ref": "#/components/schemas/InviteeRoleEnum" }, "status": { "$ref": "#/components/schemas/InviteStatusChoicesEnum" }, "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/organizations/orgR6zUBwMHop2mgGygtFd6c/invites/f3ba00b2-372b-4283-9d57-adbe7d5b1bf1/" }, "invited_by": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/users/bob/" }, "organization_name": { "type": "string" }, "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" }, "invitee": { "type": "string" } }, "required": [ "created", "invited_by", "invitee", "invitee_role", "modified", "organization_name", "status", "url" ] }, "InviteStatusChoicesEnum": { "enum": [ "accepted", "cancelled", "declined", "expired", "pending", "resent" ], "type": "string", "description": "* `accepted` - Accepted\n* `cancelled` - Cancelled\n* `declined` - Declined\n* `expired` - Expired\n* `pending` - Pending\n* `resent` - Resent" }, "InviteeRoleEnum": { "enum": [ "admin", "member" ], "type": "string", "description": "* `admin` - admin\n* `member` - member" }, "Language": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "code": { "type": "string", "maxLength": 10 }, "featured": { "type": "boolean" }, "transcription_services": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string" } }, "readOnly": true }, "translation_services": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string" } }, "readOnly": true }, "regions": { "type": "array", "items": { "$ref": "#/components/schemas/LanguageRegion" } } }, "required": [ "code", "name", "regions", "transcription_services", "translation_services" ] }, "LanguageList": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "code": { "type": "string", "maxLength": 10 }, "featured": { "type": "boolean" }, "transcription_services": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "readOnly": true }, "translation_services": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "readOnly": true }, "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/language/en/", "readOnly": true } }, "required": [ "code", "name", "transcription_services", "translation_services", "url" ] }, "LanguageRegion": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 20 }, "name": { "type": "string", "maxLength": 200 } }, "required": [ "code", "name" ] }, "LogsRetryResponse": { "type": "object", "properties": { "detail": { "type": "string" }, "pending_uids": { "type": "array", "items": { "type": "string" } } }, "required": [ "detail", "pending_uids" ] }, "MeListResponse": { "type": "object", "properties": { "username": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "server_time": { "type": "string", "format": "date-time" }, "date_joined": { "type": "string", "format": "date-time" }, "projects_url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/bob" }, "gravatar": { "type": "string", "format": "uri", "example": "https://www.gravatar.com/avatar/5a9aec55090975e64e0f6b0a29110a5f?s=40" }, "last_login": { "type": [ "string", "null" ], "format": "date-time" }, "extra_details": { "type": "object", "properties": { "bio": { "type": "string" }, "city": { "type": "string" }, "name": { "type": "string" }, "sector": { "type": "string" }, "country": { "type": "string" }, "twitter": { "type": "string" }, "linkedin": { "type": "string" }, "instagram": { "type": "string" }, "organization": { "type": "string" }, "last_ui_language": { "type": "string" }, "organization_type": { "type": "string" }, "organization_website": { "type": "string" }, "project_views_settings": { "type": "object" }, "require_auth": { "type": "boolean" }, "newsletter_subscription": { "type": "string" } } }, "git_rev": { "oneOf": [ { "type": "boolean" }, { "type": "object", "properties": { "short": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "long": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "branch": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] }, "tag": { "oneOf": [ { "type": "string" }, { "type": "boolean" } ] } } } ] }, "social_accounts": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "uid": { "type": "string" }, "last_joined": { "type": "string", "format": "date-time" }, "date_joined": { "type": "string", "format": "date-time" }, "email": { "type": "string", "format": "email" }, "username": { "type": "string" } } } }, "validated_password": { "type": "boolean" }, "accepted_tos": { "type": "boolean" }, "organization": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/organizations/orgzeph7Ub8tVmJ82JBbH96n/" }, "name": { "type": "string" }, "uid": { "type": "string" } } }, "extra_details__uid": { "type": "string" } }, "required": [ "accepted_tos", "date_joined", "email", "extra_details", "extra_details__uid", "first_name", "git_rev", "gravatar", "last_login", "last_name", "organization", "projects_url", "server_time", "social_accounts", "username", "validated_password" ] }, "MemberListResponse": { "type": "object", "properties": { "role": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/MemberRoleEnum" } ] }, { "type": "null" } ] }, "url": { "type": [ "string", "null" ], "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/organizations/orgR6zUBwMHop2mgGygtFd6c/members/bob/" }, "user": { "type": [ "string", "null" ], "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/users/bob/" }, "user__username": { "type": [ "string", "null" ] }, "user__email": { "type": [ "string", "null" ], "format": "email" }, "user__extra_details__name": { "type": [ "string", "null" ] }, "user__has_mfa_enabled": { "type": [ "boolean", "null" ] }, "user__has_sso_enabled": { "type": [ "boolean", "null" ] }, "date_joined": { "type": [ "string", "null" ], "format": "date-time" }, "user__is_active": { "type": [ "boolean", "null" ] }, "invite": { "oneOf": [ { "$ref": "#/components/schemas/InviteResponse" }, { "type": "null" } ] } }, "required": [ "date_joined", "invite", "role", "url", "user", "user__email", "user__extra_details__name", "user__has_mfa_enabled", "user__has_sso_enabled", "user__is_active", "user__username" ] }, "MemberRoleEnum": { "enum": [ "admin", "member", "owner" ], "type": "string", "description": "* `admin` - admin\n* `member` - member\n* `owner` - owner" }, "MetadataField": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "required": { "type": "boolean" }, "options": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/MetadataFieldOption" } } }, "required": [ "label", "name" ] }, "MetadataFieldOption": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "label", "name" ] }, "NlpUsage": { "type": "object", "properties": { "total_nlp_asr_seconds": { "type": "integer" }, "total_nlp_llm_requests": { "type": "integer" }, "total_nlp_mt_characters": { "type": "integer" } }, "required": [ "total_nlp_asr_seconds", "total_nlp_llm_requests", "total_nlp_mt_characters" ] }, "NullableServiceUsageBalanceData": { "oneOf": [ { "$ref": "#/components/schemas/ServiceUsageBalanceData" }, { "type": "null" } ] }, "OneTimeAddOn": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 27 }, "created": { "type": "string", "format": "date-time", "description": "The time when the add-on purchased." }, "is_available": { "type": "boolean", "readOnly": true }, "usage_limits": { "description": "The historical usage limits when the add-on was purchased.\n Possible keys:\n \"submission_limit\", \"asr_seconds_limit\", and/or \"mt_characters_limit\"" }, "total_usage_limits": { "type": "object", "additionalProperties": {}, "description": "The total usage limits for this add-on, based on the usage_limits for a single\nadd-on.", "readOnly": true }, "limits_remaining": { "description": "The amount of each of the add-on's individual limits left to use." }, "organization": { "type": [ "string", "null" ] }, "product": { "type": [ "string", "null" ] } }, "required": [ "created", "id", "is_available", "total_usage_limits" ] }, "OpenRosaXFormResponse": { "type": "object", "properties": { "html": { "type": "object", "properties": { "head": { "type": "object", "properties": { "title": { "type": "string" }, "model": { "type": "object", "properties": { "instance": { "type": "object", "properties": { "instanceUuid": { "type": "object", "properties": { "fieldName": { "type": "string" }, "meta": { "type": "object", "properties": { "instanceID": { "type": "string" } } } } } } } } } } }, "body": { "type": "object", "properties": { "input": { "type": "object", "properties": { "label": { "type": "string" }, "hint": { "type": "string" } } } } } } } }, "required": [ "html" ] }, "OperationEnum": { "enum": [ "accept" ], "type": "string", "description": "* `accept` - accept" }, "OrganizationResponse": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/organizations/orgzeph7Ub8tVmJ82JBbH96n/", "readOnly": true }, "name": { "type": "string", "readOnly": true, "maxLength": 200 }, "website": { "type": "string", "readOnly": true, "maxLength": 255 }, "organization_type": { "allOf": [ { "$ref": "#/components/schemas/OrganizationTypeEnum" } ], "readOnly": true }, "created": { "type": "string", "format": "date-time", "readOnly": true }, "modified": { "type": "string", "format": "date-time", "readOnly": true }, "is_owner": { "type": "boolean", "readOnly": true }, "is_mmo": { "type": "boolean", "readOnly": true }, "request_user_role": { "allOf": [ { "$ref": "#/components/schemas/MemberRoleEnum" } ], "readOnly": true }, "members": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/organizations/orgzeph7Ub8tVmJ82JBbH96n/members/", "readOnly": true }, "assets": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/organizations/orgzeph7Ub8tVmJ82JBbH96n/assets/", "readOnly": true }, "service_usage": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/organizations/orgzeph7Ub8tVmJ82JBbH96n/service_usage/", "readOnly": true }, "asset_usage": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/organizations/orgzeph7Ub8tVmJ82JBbH96n/assets_usage/", "readOnly": true } }, "required": [ "asset_usage", "assets", "created", "id", "is_mmo", "is_owner", "members", "modified", "name", "organization_type", "request_user_role", "service_usage", "url", "website" ] }, "OrganizationServiceUsageResponse": { "type": "object", "properties": { "total_nlp_usage": { "type": "object", "properties": { "asr_seconds_current_period": { "type": "integer" }, "llm_requests_current_period": { "type": "integer" }, "mt_characters_current_period": { "type": "integer" }, "asr_seconds_all_time": { "type": "integer" }, "llm_requests_all_time": { "type": "integer" }, "mt_characters_all_time": { "type": "integer" } }, "required": [ "asr_seconds_all_time", "asr_seconds_current_period", "llm_requests_all_time", "llm_requests_current_period", "mt_characters_all_time", "mt_characters_current_period" ] }, "total_storage_bytes": { "type": "integer" }, "total_submission_count": { "type": "object", "properties": { "all_time": { "type": "integer" }, "current_period": { "type": "integer" } }, "required": [ "all_time", "current_period" ] }, "balances": { "$ref": "#/components/schemas/ServiceUsageBalances" }, "current_period_start": { "type": "string", "format": "date-time" }, "current_period_end": { "type": "string", "format": "date-time" }, "last_updated": { "type": "string", "format": "date-time" } }, "required": [ "balances", "current_period_end", "current_period_start", "last_updated", "total_nlp_usage", "total_storage_bytes", "total_submission_count" ] }, "OrganizationTypeEnum": { "enum": [ "non-profit", "government", "educational", "commercial", "none" ], "type": "string", "description": "* `non-profit` - Non-profit organization\n* `government` - Government institution\n* `educational` - Educational organization\n* `commercial` - A commercial/for-profit company\n* `none` - I am not associated with any organization" }, "PaginatedAccessLogResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AccessLogResponse" } } } }, "PaginatedAssetCountResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AssetCountResponse" } } } }, "PaginatedAssetList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } }, "metadata": { "type": "object", "properties": { "languages": { "type": "array", "items": { "type": "string" }, "example": [ "English (en)" ] }, "countries": { "type": "array", "items": { "type": "array", "items": { "type": "string" } }, "example": [ [ "FRA", "France" ] ] }, "sectors": { "type": "array", "items": { "type": "array", "items": { "type": "string" } }, "example": [ [ "Public Administration", "Public Administration" ] ] }, "organizations": { "type": "array", "items": { "type": "string" }, "example": [ "Kobotoolbox" ] } } } }, "PaginatedAssetMinimalListList": { "type": "object", "required": [ "results" ], "properties": { "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AssetMinimalList" } } } }, "PaginatedAssetSnapshotResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AssetSnapshotResponse" } } } }, "PaginatedAssetSubscriptionResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AssetSubscriptionResponse" } } } }, "PaginatedAssetUsageResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AssetUsageResponse" } } } }, "PaginatedAuditLogResponseList": { "type": "object", "required": [ "results" ], "properties": { "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogResponse" } } } }, "PaginatedCustomAssetUsageList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CustomAssetUsage" } } } }, "PaginatedDataResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/DataResponse" } } } }, "PaginatedDataResponseXMLList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/DataResponseXML" } } } }, "PaginatedEmailAddressList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAddress" } } } }, "PaginatedExportResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ExportResponse" } } } }, "PaginatedExportSettingResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ExportSettingResponse" } } } }, "PaginatedFilesResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/FilesResponse" } } } }, "PaginatedHistoryListResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryListResponse" } } } }, "PaginatedHookList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Hook" } } } }, "PaginatedHookLogList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/HookLog" } } } }, "PaginatedImportResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ImportResponse" } } } }, "PaginatedInviteResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/InviteResponse" } } } }, "PaginatedLanguageListList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/LanguageList" } } } }, "PaginatedMemberListResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/MemberListResponse" } } } }, "PaginatedOneTimeAddOnList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/OneTimeAddOn" } } } }, "PaginatedOrganizationResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationResponse" } } } }, "PaginatedPairedDataResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/PairedDataResponse" } } } }, "PaginatedPermissionResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionResponse" } } } }, "PaginatedProductList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } } }, "PaginatedProjectHistoryLogResponseList": { "type": "object", "required": [ "results" ], "properties": { "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectHistoryLogResponse" } } } }, "PaginatedProjectInviteResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectInviteResponse" } } } }, "PaginatedProjectViewAssetResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectViewAssetResponse" } } } }, "PaginatedProjectViewListResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectViewListResponse" } } } }, "PaginatedProjectViewUserResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectViewUserResponse" } } } }, "PaginatedScimGroupList": { "type": "object", "required": [ "schemas", "totalResults", "itemsPerPage", "startIndex", "Resources" ], "properties": { "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] }, "totalResults": { "type": "integer", "example": 100 }, "itemsPerPage": { "type": "integer", "example": 10 }, "startIndex": { "type": "integer", "example": 1 }, "Resources": { "type": "array", "items": { "$ref": "#/components/schemas/ScimGroup" } } } }, "PaginatedScimUserList": { "type": "object", "required": [ "schemas", "totalResults", "itemsPerPage", "startIndex", "Resources" ], "properties": { "schemas": { "type": "array", "items": { "type": "string" }, "example": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] }, "totalResults": { "type": "integer", "example": 100 }, "itemsPerPage": { "type": "integer", "example": 10 }, "startIndex": { "type": "integer", "example": 1 }, "Resources": { "type": "array", "items": { "$ref": "#/components/schemas/ScimUser" } } } }, "PaginatedSocialAccountList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SocialAccount" } } } }, "PaginatedSubscriptionList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } } } }, "PaginatedSuperUserAccessLogResponseList": { "type": "object", "required": [ "results" ], "properties": { "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SuperUserAccessLogResponse" } } } }, "PaginatedTagListResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TagListResponse" } } } }, "PaginatedTranscriptionServiceList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TranscriptionService" } } } }, "PaginatedTranslationServiceList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TranslationService" } } } }, "PaginatedUserListResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/UserListResponse" } } } }, "PaginatedUserReportsListResponseList": { "type": "object", "required": [ "results" ], "properties": { "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/UserReportsListResponse" } } } }, "PaginatedVersionListResponseList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=400&limit=100" }, "previous": { "type": [ "string", "null" ], "nullable": true, "format": "uri", "example": "https://kf.kobotoolbox.org/accounts/?start=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/VersionListResponse" } } } }, "PairedData": { "type": "object", "properties": { "source": { "type": "string", "format": "uri" }, "fields": { "type": "array", "items": { "type": "string" } }, "filename": { "type": "string" }, "source__name": { "type": "string", "readOnly": true } }, "required": [ "filename", "source", "source__name" ] }, "PairedDataResponse": { "type": "object", "properties": { "source": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/" }, "source__name": { "type": "string", "readOnly": true }, "fields": { "type": "array", "items": { "type": "string" } }, "filename": { "type": "string" }, "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a5owyo85mHyFazzgsZK45c/paired-data/pd9CWSKADt4T7h5bMKwhLqq/" } }, "required": [ "fields", "filename", "source", "source__name", "url" ] }, "PatchedAdvancedFeaturePatchRequest": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/ActionEnum" }, "question_xpath": { "type": "string" }, "params": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/RequestNLPActionParams" }, { "$ref": "#/components/schemas/RequestManualQualActionParams" }, { "$ref": "#/components/schemas/RequestAutomaticQualActionParams" } ] } } } }, "PatchedAssetPatchRequest": { "oneOf": [ { "$ref": "#/components/schemas/PatchedAssetPatchRequestContent" }, { "$ref": "#/components/schemas/PatchedAssetPatchRequestDataSharing" }, { "$ref": "#/components/schemas/PatchedAssetPatchRequestTagString" } ] }, "PatchedAssetPatchRequestContent": { "type": "object", "properties": { "content": { "type": "string" }, "name": { "type": "string" } } }, "PatchedAssetPatchRequestDataSharing": { "type": "object", "properties": { "data_sharing": { "$ref": "#/components/schemas/AssetPatchRequestDataSharingFields" } } }, "PatchedAssetPatchRequestTagString": { "type": "object", "properties": { "tag_string": { "type": "string" } } }, "PatchedBulkActionPatchRequest": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/BulkActionPatchRequestStatusEnum" } } }, "PatchedCurrentUser": { "type": "object", "properties": { "username": { "type": "string", "description": "Required. 150 characters or fewer. Letters, digits and @/./+/-/_ only.", "pattern": "^[\\w.@+-]+$", "maxLength": 150 }, "first_name": { "type": "string", "maxLength": 150 }, "last_name": { "type": "string", "maxLength": 150 }, "email": { "type": "string", "format": "email", "readOnly": true, "title": "Email address" }, "is_superuser": { "type": "boolean", "readOnly": true, "title": "Superuser status", "description": "Designates that this user has all permissions without explicitly assigning them." }, "server_time": { "type": "string", "format": "date-time", "readOnly": true }, "date_joined": { "type": "string", "format": "date-time", "readOnly": true }, "projects_url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/bob", "readOnly": true }, "gravatar": { "type": "string", "format": "uri", "example": "https://www.gravatar.com/avatar/5a9aec55090975e64e0f6b0a29110a5f?s=40", "readOnly": true }, "last_login": { "type": [ "string", "null" ], "format": "date-time" }, "extra_details": { "type": "object", "properties": { "bio": { "type": "string" }, "city": { "type": "string" }, "name": { "type": "string" }, "sector": { "type": "string" }, "country": { "type": "string" }, "twitter": { "type": "string" }, "linkedin": { "type": "string" }, "instagram": { "type": "string" }, "organization": { "type": "string" }, "last_ui_language": { "type": "string" }, "organization_type": { "type": "string" }, "organization_website": { "type": "string" }, "project_views_settings": { "type": "object" }, "require_auth": { "type": "boolean" }, "newsletter_subscription": { "type": "string" } } }, "current_password": { "type": "string", "writeOnly": true }, "new_password": { "type": "string", "writeOnly": true }, "git_rev": { "type": "string", "readOnly": true }, "social_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/SocialAccount" }, "readOnly": true }, "validated_password": { "type": "boolean", "readOnly": true }, "accepted_tos": { "type": "boolean", "description": "Verifies user acceptance of terms of service (tos) by checking that the tos\nendpoint was called and stored the current time in the `private_data` property", "readOnly": true }, "organization": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/organizations/orgzeph7Ub8tVmJ82JBbH96n/" }, "name": { "type": "string" }, "uid": { "type": "string" } }, "readOnly": true }, "extra_details__uid": { "type": "string", "readOnly": true } } }, "PatchedDataBulkUpdate": { "type": "object", "properties": { "payload": { "type": "object", "properties": { "submission_ids": { "type": "array", "items": { "type": "integer" } }, "data": { "type": "object", "properties": { "field_to_update": { "type": "string" } } } } } } }, "PatchedDataSupplementPayload": { "type": "object", "properties": { "_version": { "type": "string", "example": "20250820" } }, "additionalProperties": { "$ref": "#/components/schemas/PatchedDataSupplementPayloadOneOf" }, "required": [ "_version" ], "patternProperties": { "^(?!_version$).*": { "$ref": "#/components/schemas/PatchedDataSupplementPayloadOneOf" } } }, "PatchedDataSupplementPayloadOneOf": { "type": "object", "properties": { "manual_transcription": { "type": "object", "properties": { "language": { "type": "string" }, "locale": { "type": "string" }, "value": { "type": "string", "nullable": true } }, "additionalProperties": false, "required": [ "language", "value" ] }, "manual_translation": { "type": "object", "properties": { "language": { "type": "string" }, "locale": { "type": "string" }, "value": { "type": "string", "nullable": true } }, "additionalProperties": false, "required": [ "language", "value" ] }, "automatic_google_transcription": { "type": "object", "properties": { "language": { "type": "string" }, "locale": { "type": "string" }, "accepted": { "type": "boolean" }, "value": { "enum": [ null ], "nullable": true } }, "additionalProperties": false, "required": [ "language" ] }, "automatic_google_translation": { "type": "object", "properties": { "language": { "type": "string" }, "locale": { "type": "string" }, "accepted": { "type": "boolean" }, "value": { "enum": [ null ], "nullable": true } }, "additionalProperties": false, "required": [ "language" ] }, "manual_qual": { "oneOf": [ { "$ref": "#/components/schemas/DataSupplementManualQualDataInteger" }, { "$ref": "#/components/schemas/DataSupplementManualQualDataText" }, { "$ref": "#/components/schemas/DataSupplementManualQualDataSelectOne" }, { "$ref": "#/components/schemas/DataSupplementManualQualDataSelectMultiple" }, { "$ref": "#/components/schemas/DataSupplementManualQualDataTags" }, { "$ref": "#/components/schemas/PatchedDataSupplementPayloadOneOfVerification" } ] }, "automatic_bedrock_qual": { "oneOf": [ { "$ref": "#/components/schemas/PatchedDataSupplementPayloadOneOfAutomaticQual" }, { "$ref": "#/components/schemas/PatchedDataSupplementPayloadOneOfVerification" } ] } }, "additionalProperties": false, "anyOf": [ { "required": [ "manual_transcription" ] }, { "required": [ "manual_translation" ] }, { "required": [ "automatic_google_transcription" ] }, { "required": [ "automatic_google_translation" ] }, { "required": [ "manual_qual" ] }, { "required": [ "automatic_bedrock_qual" ] } ] }, "PatchedDataSupplementPayloadOneOfAutomaticQual": { "type": "object", "additionalProperties": false, "properties": { "uuid": { "type": "string", "format": "uuid" } }, "required": [ "uuid" ] }, "PatchedDataSupplementPayloadOneOfVerification": { "type": "object", "additionalProperties": false, "properties": { "uuid": { "type": "string", "format": "uuid" }, "verified": { "type": "boolean" } }, "required": [ "uuid", "verified" ] }, "PatchedDataValidationStatusUpdatePayload": { "type": "object", "properties": { "validation_status.uid": { "type": "string" } } }, "PatchedDataValidationStatusesUpdatePayload": { "type": "object", "properties": { "payload": { "type": "object", "properties": { "submission_ids": { "type": "array", "items": { "type": "integer" } }, "validation_status.uid": { "$ref": "#/components/schemas/DataValidationStatusUidEnum" } } } } }, "PatchedDeploymentPatchRequest": { "type": "object", "properties": { "active": { "type": "boolean" }, "version_id": { "type": "string" } } }, "PatchedExportSettingUpdatePayload": { "type": "object", "properties": { "name": { "type": "string" }, "export_settings": { "type": "object", "properties": { "fields_from_all_versions": { "type": "boolean" }, "group_sep": { "type": "string" }, "hierarchy_in_labels": { "type": "boolean" }, "lang": { "type": "string" }, "multiple_select": { "type": "string" }, "type": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } } } } } }, "PatchedHook": { "type": "object", "properties": { "active": { "type": "boolean" }, "asset": { "type": "integer", "readOnly": true }, "auth_level": { "$ref": "#/components/schemas/AuthLevelEnum" }, "date_modified": { "type": "string", "format": "date-time", "readOnly": true }, "email_notification": { "type": "boolean" }, "endpoint": { "type": "string", "maxLength": 500 }, "export_type": { "$ref": "#/components/schemas/ExportTypeEnum" }, "failed_count": { "type": "integer", "readOnly": true }, "logs_url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/hooks/hZzzeedWxQoFHgibsTCysv/logs/", "readOnly": true }, "name": { "type": "string", "maxLength": 255 }, "payload_template": { "type": [ "string", "null" ] }, "pending_count": { "type": "integer", "readOnly": true }, "settings": { "type": "object", "properties": { "password": { "type": "string" }, "username": { "type": "string" }, "custom_headers": { "type": "object", "properties": { "value_field": { "type": "string" }, "value_field_2": { "type": "string" } } } } }, "subset_fields": { "type": "array", "items": { "type": "string" } }, "success_count": { "type": "integer", "readOnly": true }, "uid": { "type": "string", "readOnly": true }, "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/", "readOnly": true } } }, "PatchedHookLog": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/aTPPUDScaFZkvBzd8FyK4Q/hooks/hsw3Ec5vz7Lqg7TrwrxdaS/logs/hl8Ldv5m84SBpU5UB5J7QBD/", "readOnly": true }, "uid": { "type": "string", "readOnly": true }, "submission_id": { "type": "integer", "readOnly": true }, "tries": { "type": "integer", "readOnly": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/HookLogStatusEnum" } ], "readOnly": true }, "status_str": { "type": "string" }, "status_code": { "type": [ "integer", "null" ], "readOnly": true }, "message": { "type": "string", "readOnly": true }, "date_modified": { "type": "string", "format": "date-time", "readOnly": true } } }, "PatchedInvitePatchPayload": { "oneOf": [ { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/InviteStatusChoicesEnum" } }, "required": [ "status" ] }, { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/InviteeRoleEnum" } }, "required": [ "role" ] } ] }, "PatchedInviteUpdatePayload": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/InviteStatusChoicesEnum" } } }, "PatchedMemberPatchRequest": { "type": "object", "properties": { "role": { "$ref": "#/components/schemas/InviteeRoleEnum" } } }, "PatchedOrganizationPatchPayload": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "website": { "type": "string", "maxLength": 255 }, "organization_type": { "$ref": "#/components/schemas/OrganizationTypeEnum" } } }, "PatchedPairedDataPatchPayload": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "string" } }, "filename": { "type": "string" } } }, "PatchedPermissionAssignmentCloneRequest": { "type": "object", "properties": { "clone_from": { "type": "string" } } }, "PatchedScimGroup": { "type": "object", "description": "Serializes a Django ScimGroup to match the SCIM 2.0 Group schema.", "properties": { "schemas": { "readOnly": true }, "id": { "type": "string", "readOnly": true }, "displayName": { "type": "string" }, "externalId": { "type": "string" }, "members": { "readOnly": true }, "meta": { "type": "object", "additionalProperties": {}, "readOnly": true } } }, "PatchedScimUser": { "type": "object", "description": "Serializes a Django User to match the SCIM 2.0 User schema.", "properties": { "schemas": { "readOnly": true }, "id": { "type": "string", "readOnly": true }, "userName": { "type": "string" }, "name": { "type": "object", "additionalProperties": {}, "readOnly": true }, "emails": { "readOnly": true }, "active": { "type": "boolean" }, "meta": { "type": "object", "additionalProperties": {}, "readOnly": true } } }, "PermissionAssignmentBulkRequest": { "type": "object", "properties": { "user": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/users/bob/" }, "permission": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/permission-assignments/pGaXCTDAbdZKLXoXAXd3M4/" } }, "required": [ "permission", "user" ] }, "PermissionAssignmentCreateRequest": { "oneOf": [ { "type": "object", "properties": { "permission": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/permissions/change_asset/" }, "user": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/users/bob/" } }, "additionalProperties": false, "required": [ "permission", "user" ] }, { "type": "object", "properties": { "partial_permission": { "type": "array", "items": { "type": "object", "properties": { "filter": { "type": "array", "items": { "type": "object", "properties": { "_submitted_by": { "type": "object", "properties": { "$in": { "type": "array", "items": { "type": "string" } } } } } } }, "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/permission-assignments/pGaXCTDAbdZKLXoXAXd3M4/" } } } }, "permission": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/permissions/change_asset/" }, "user": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/users/bob/" } }, "required": [ "partial_permission", "permission", "user" ] } ] }, "PermissionAssignmentResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/permission-assignments/pGaXCTDAbdZKLXoXAXd3M4/" }, "user": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/users/bob/" }, "permission": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/permissions/change_asset/" }, "label": { "type": "string", "readOnly": true } }, "required": [ "label", "permission", "url", "user" ] }, "PermissionResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/permissions/change_submissions/", "readOnly": true }, "codename": { "type": "string" }, "implied": { "type": "array", "items": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/permissions/change_submissions/" } }, "contradictory": { "type": "array", "items": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/permissions/change_submissions/" } }, "name": { "type": "string" } }, "required": [ "codename", "contradictory", "implied", "name", "url" ] }, "Price": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 255 }, "nickname": { "type": "string", "description": "A brief description of the plan, hidden from customers.", "maxLength": 250 }, "currency": { "type": "string", "description": "Three-letter ISO currency code", "maxLength": 3 }, "type": { "allOf": [ { "$ref": "#/components/schemas/StripePriceType" } ], "description": "Whether the price is for a one-time purchase or a recurring (subscription) purchase.\n\n* `one_time` - One-time\n* `recurring` - Recurring" }, "recurring": { "oneOf": [ { "$ref": "#/components/schemas/Recurring" }, { "type": "null" } ] }, "unit_amount": { "type": [ "integer", "null" ], "maximum": 9223372036854775807, "minimum": -9223372036854775808, "format": "int64", "description": "The unit amount in cents to be charged, represented as a whole integer if possible. Null if a sub-cent precision is required." }, "human_readable_price": { "type": "string", "readOnly": true }, "metadata": { "oneOf": [ {}, { "type": "null" } ], "description": "A set of key/value pairs that you can attach to an object. It can be useful for storing additional information about an object in a structured format." }, "active": { "type": "boolean", "description": "Whether the price can be used for new purchases." }, "product": { "type": "string", "description": "The product this price is associated with." }, "transform_quantity": { "oneOf": [ {}, { "type": "null" } ], "description": "Apply a transformation to the reported usage or set quantity before computing the amount billed. Cannot be combined with `tiers`." } }, "required": [ "active", "currency", "human_readable_price", "id", "product", "recurring", "type" ] }, "PriceWithProduct": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 255 }, "nickname": { "type": "string", "description": "A brief description of the plan, hidden from customers.", "maxLength": 250 }, "currency": { "type": "string", "description": "Three-letter ISO currency code", "maxLength": 3 }, "type": { "allOf": [ { "$ref": "#/components/schemas/StripePriceType" } ], "description": "Whether the price is for a one-time purchase or a recurring (subscription) purchase.\n\n* `one_time` - One-time\n* `recurring` - Recurring" }, "recurring": { "oneOf": [ { "$ref": "#/components/schemas/Recurring" }, { "type": "null" } ] }, "unit_amount": { "type": [ "integer", "null" ], "maximum": 9223372036854775807, "minimum": -9223372036854775808, "format": "int64", "description": "The unit amount in cents to be charged, represented as a whole integer if possible. Null if a sub-cent precision is required." }, "human_readable_price": { "type": "string", "readOnly": true }, "metadata": { "oneOf": [ {}, { "type": "null" } ], "description": "A set of key/value pairs that you can attach to an object. It can be useful for storing additional information about an object in a structured format." }, "active": { "type": "boolean", "description": "Whether the price can be used for new purchases." }, "product": { "$ref": "#/components/schemas/BaseProduct" }, "transform_quantity": { "oneOf": [ {}, { "type": "null" } ], "description": "Apply a transformation to the reported usage or set quantity before computing the amount billed. Cannot be combined with `tiers`." } }, "required": [ "active", "currency", "human_readable_price", "id", "product", "recurring", "type" ] }, "Product": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 255 }, "name": { "type": "string", "description": "The product's name, meant to be displayable to the customer. Applicable to both `service` and `good` types.", "maxLength": 5000 }, "description": { "type": [ "string", "null" ], "description": "A description of this object." }, "type": { "allOf": [ { "$ref": "#/components/schemas/StripeProductType" } ], "description": "The type of the product. The product is either of type `good`, which is eligible for use with Orders and SKUs, or `service`, which is eligible for use with Subscriptions and Plans.\n\n* `good` - Good\n* `service` - Service" }, "prices": { "type": "array", "items": { "$ref": "#/components/schemas/Price" } }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "readOnly": true } }, "required": [ "id", "metadata", "name", "prices", "type" ] }, "ProjectHistoryLogResponse": { "type": "object", "properties": { "user": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/users/bob/" }, "user_uid": { "type": "string" }, "username": { "type": "string" }, "action": { "type": "string" }, "metadata": { "type": "object", "properties": { "source": { "type": "string" }, "asset_uid": { "type": "string" }, "ip_address": { "type": "string" }, "cloned_from": { "type": "string" }, "log_subtype": { "type": "string" }, "paired-data": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "string" } }, "source_uid": { "type": "string" }, "source_name": { "type": "string" } } }, "username": { "type": "string" }, "settings": { "type": "object", "properties": { "sector": { "type": "object", "properties": { "new": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } }, "old": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } } } }, "country": { "type": "object", "properties": { "added": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } }, "removed": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } } } }, "description": { "type": "object", "properties": { "new": { "type": "string" }, "old": { "type": "string" } } }, "country_codes": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array", "items": { "type": "string" } } } }, "data-table": { "type": "object", "properties": { "new": { "type": "object" }, "old": { "type": "object" } } } } }, "asset-files": { "type": "object", "properties": { "uid": { "type": "string" }, "filename": { "type": "string" }, "md5_hash": { "type": "string" }, "download_url": { "type": "string" } } }, "permissions": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array", "items": { "type": "string" } }, "username": { "type": "string" } } }, "project_owner": { "type": "string" }, "latest_version_uid": { "type": "string" }, "submission": { "type": "object", "properties": { "root_uuid": { "type": "string" }, "submitted_by": { "type": "string" }, "status": { "type": "string" } } }, "hook": { "type": "object", "properties": { "uid": { "type": "string" }, "active": { "type": "boolean" }, "endpoint": { "type": "boolean" } } }, "bulk_action": { "type": "object", "properties": { "uid": { "type": "string" }, "action_id": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "question_xpath": { "type": "string" }, "params": { "type": "object" }, "created_by": { "type": "string" }, "cancelled_by": { "type": "string" }, "total_count": { "type": "integer" }, "processed_count": { "type": "integer" }, "completed_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "cancelled_count": { "type": "integer" } } }, "name": { "type": "object", "properties": { "new": { "type": "string" }, "old": { "type": "string" } } }, "shared_fields": { "type": "object", "properties": { "added": { "type": "array", "items": { "type": "string" } }, "removed": { "type": "array", "items": { "type": "string" } } } } } }, "date_created": { "type": "string", "format": "date-time" } }, "required": [ "action", "date_created", "metadata", "user", "user_uid", "username" ] }, "ProjectInviteCreatePayload": { "type": "object", "properties": { "recipient": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/users/bob/" }, "assets": { "type": "array", "items": { "type": "string" } } }, "required": [ "assets", "recipient" ] }, "ProjectInviteResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/project-ownership/invites/poi52fGkwDjQeZkUxcaou39q/" }, "sender | recipient": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/users/bob/" }, "status": { "$ref": "#/components/schemas/InviteStatusChoicesEnum" }, "date_created": { "type": "string", "format": "date-time" }, "date_modified": { "type": "string", "format": "date-time" }, "transfers": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/project-ownership/invites/poi52fGkwDjQeZkUxcaou39q/transfers/pot54pTqM5qwKdZ4wnNdiwDY/" }, "asset": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/" }, "status": { "type": "string" }, "error": { "type": "string" }, "date_modified": { "type": "string", "format": "date-time" } } } } }, "required": [ "date_created", "date_modified", "sender | recipient", "status", "transfers", "url" ] }, "ProjectViewAssetResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/project-views/pvyHWBnzRw3GCJpFs6cMdem/assets/" }, "date_created": { "type": "string", "format": "date-time" }, "date_modified": { "type": "string", "format": "date-time" }, "date_deployed": { "type": "string", "format": "date-time" }, "owner": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/project-views/pvyHWBnzRw3GCJpFs6cMdem/users/" }, "owner__username": { "type": "string" }, "owner__email": { "type": "string", "format": "email" }, "owner__name": { "type": "string" }, "owner__organization": { "type": "string" }, "uid": { "type": "string" }, "name": { "type": "string" }, "settings": { "type": "object", "properties": { "sector": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } }, "country": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } } } }, "description": { "type": "string" }, "collects_pii": { "type": "string" }, "organization": { "type": "string" }, "country_codes": { "type": "array", "items": { "type": "string" } }, "operational_purpose": { "type": "string" } } }, "languages": { "type": "array", "items": { "type": "string" } }, "has_deployment": { "type": "boolean" }, "deployment__active": { "type": "boolean" }, "deployment__submission_count": { "type": "integer" }, "deployment_status": { "type": "string" }, "asset_type": { "type": "string" }, "downloads": { "type": "array", "items": { "type": "object", "properties": { "format": { "type": "string" }, "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/aTPPUDScaFZkvBzd8FyK4Q/" } } } }, "owner_label": { "type": "string" } }, "required": [ "asset_type", "date_created", "date_deployed", "date_modified", "deployment__active", "deployment__submission_count", "deployment_status", "downloads", "has_deployment", "languages", "name", "owner", "owner__email", "owner__name", "owner__organization", "owner__username", "owner_label", "settings", "uid", "url" ] }, "ProjectViewExportCreateResponse": { "type": "object", "properties": { "status": { "type": "string", "maxLength": 32 } }, "required": [ "status" ] }, "ProjectViewExportResponse": { "type": "object", "properties": { "status": { "type": "string", "maxLength": 32 }, "result": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/private-media/bob/exports/assets-bob-view_pvNNUan8EBhzfkrv6sCNuzR-2025-08-11T143443Z.csv" } }, "required": [ "result", "status" ] }, "ProjectViewListResponse": { "type": "object", "properties": { "uid": { "type": "string", "maxLength": 32 }, "name": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/private-media/bob/exports/assets-bob-view_pvNNUan8EBhzfkrv6sCNuzR-2025-08-11T143443Z.csv" }, "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/project-views/pvyHWBnzRw3GCJpFs6cMdem/" }, "assets": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/project-views/pvyHWBnzRw3GCJpFs6cMdem/assets/" }, "assets_export": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/project-views/pvyHWBnzRw3GCJpFs6cMdem/assets/export/" }, "users": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/project-views/pvyHWBnzRw3GCJpFs6cMdem/users/" }, "users_export": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/project-views/pvyHWBnzRw3GCJpFs6cMdem/users/export/" }, "countries": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } }, "assigned_users": { "type": "array", "items": { "type": "string" } } }, "required": [ "assets", "assets_export", "assigned_users", "countries", "name", "permissions", "uid", "url", "users", "users_export" ] }, "ProjectViewUserResponse": { "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" }, "is_superuser": { "type": "boolean" }, "date_joined": { "type": "string", "format": "date-time" }, "last_login": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "email": { "type": "string", "format": "email" }, "asset_count": { "type": "integer" }, "metadata": { "type": "object", "properties": { "city": { "type": "string" }, "name": { "type": "string" }, "sector": { "type": "string" }, "country": { "type": "string" }, "organization": { "type": "string" }, "last_ui_language": { "type": "string" }, "organization_type": { "type": "string" }, "organization_website": { "type": "string" }, "project_view_settings": { "type": "object", "properties": { "my_project_view_name": { "type": "object", "properties": { "order": { "type": "object" }, "fields": { "type": "array", "items": { "type": "string" } }, "filters": { "type": "array", "items": { "type": "string" } } } } } } } } }, "required": [ "asset_count", "date_joined", "email", "id", "is_active", "is_superuser", "last_login", "metadata", "username" ] }, "ProrationBehaviorEnum": { "enum": [ "always_invoice", "create_prorations", "none" ], "type": "string", "description": "* `always_invoice` - Always invoice\n* `create_prorations` - Create prorations\n* `none` - None" }, "QATagTracker": { "type": "object", "properties": { "value": { "type": "string", "maxLength": 255 } }, "required": [ "value" ] }, "QualSelectQuestionParamsTypeEnum": { "type": "string", "enum": [ "qualSelectMultiple", "qualSelectOne" ] }, "QualSimpleQuestionParamsTypeEnum": { "type": "string", "enum": [ "qualInteger", "qualTags", "qualText", "qualNote", "qualAutoKeywordCount" ] }, "Recurring": { "type": "object", "properties": { "interval": { "$ref": "#/components/schemas/StripeIntervalEnum" }, "interval_count": { "type": "integer" }, "meter": { "type": [ "string", "null" ] }, "usage_type": { "$ref": "#/components/schemas/StripeUsageType" } }, "required": [ "interval", "interval_count", "usage_type" ] }, "ReportResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a5owyo85mHyFazzgsZK45c/reports/" }, "count": { "type": "integer" }, "list": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "row": { "type": "object", "properties": { "type": { "type": "string" } } }, "data": { "type": "object", "properties": { "total_count": { "type": "integer" }, "not_provided": { "type": "integer" }, "provided": { "type": "integer" }, "show_graph": { "type": "boolean" } } }, "kuid": { "type": "string" }, "style": { "type": "object" } } } } }, "required": [ "count", "list", "url" ] }, "RequestAutomaticQualActionParams": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } }, "additionalProperties": false, "required": [ "uuid" ] }, "RequestManualQualActionParams": { "anyOf": [ { "$ref": "#/components/schemas/RequestQualSimpleQuestionParams" }, { "$ref": "#/components/schemas/RequestQualSelectQuestionParams" } ] }, "RequestNLPActionParams": { "type": "object", "additionalProperties": false, "properties": { "language": { "type": "string" } }, "required": [ "language" ] }, "RequestQualSelectQuestionParams": { "type": "object", "additionalProperties": false, "properties": { "uuid": { "type": "string", "format": "uuid" }, "type": { "$ref": "#/components/schemas/QualSelectQuestionParamsTypeEnum" }, "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "choices": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "uuid": { "type": "string", "format": "uuid" }, "hint": { "type": "object", "additionalProperties": false, "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "required": "labels" } }, "required": [ "labels", "uuid" ] } }, "hint": { "type": "object", "additionalProperties": false, "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "required": "labels" } }, "required": [ "uuid", "type", "labels", "choices" ] }, "RequestQualSimpleQuestionParams": { "type": "object", "additionalProperties": false, "properties": { "uuid": { "type": "string", "format": "uuid" }, "type": { "$ref": "#/components/schemas/QualSimpleQuestionParamsTypeEnum" }, "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "hint": { "type": "object", "additionalProperties": false, "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "required": "labels" } }, "required": [ "uuid", "type", "labels" ] }, "ResponseAutomaticQualActionParams": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } }, "additionalProperties": false, "required": [ "uuid" ] }, "ResponseManualQualActionParams": { "anyOf": [ { "$ref": "#/components/schemas/ResponseQualSimpleQuestionParams" }, { "$ref": "#/components/schemas/ResponseQualSelectQuestionParams" } ] }, "ResponseNLPActionParams": { "type": "object", "additionalProperties": false, "properties": { "language": { "type": "string" } }, "required": [ "language" ] }, "ResponseQualSelectQuestionParams": { "type": "object", "additionalProperties": false, "properties": { "uuid": { "type": "string", "format": "uuid" }, "type": { "$ref": "#/components/schemas/QualSelectQuestionParamsTypeEnum" }, "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "choices": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "uuid": { "type": "string", "format": "uuid" }, "options": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "hint": { "type": "object", "additionalProperties": false, "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "required": "labels" } }, "required": [ "labels", "uuid" ] } }, "options": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "hint": { "type": "object", "additionalProperties": false, "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "required": "labels" } }, "required": [ "uuid", "type", "labels", "choices" ] }, "ResponseQualSimpleQuestionParams": { "type": "object", "additionalProperties": false, "properties": { "uuid": { "type": "string", "format": "uuid" }, "type": { "$ref": "#/components/schemas/QualSimpleQuestionParamsTypeEnum" }, "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "options": { "type": "object", "properties": { "deleted": { "type": "boolean" } } }, "hint": { "type": "object", "additionalProperties": false, "labels": { "type": "object", "properties": { "_default": { "type": "string" } }, "additionalProperties": { "type": "string" }, "required": [ "_default" ] }, "required": "labels" } }, "required": [ "uuid", "type", "labels" ] }, "ScimError": { "type": "object", "description": "Serializes SCIM 2.0 Error responses matching RFC7644", "properties": { "schemas": { "type": "array", "items": { "type": "string" }, "default": [ "urn:ietf:params:scim:api:messages:2.0:Error" ] }, "detail": { "type": "string", "description": "A detailed, human-readable message." }, "status": { "type": "string", "description": "The HTTP status code." } }, "required": [ "detail", "status" ] }, "ScimGroup": { "type": "object", "description": "Serializes a Django ScimGroup to match the SCIM 2.0 Group schema.", "properties": { "schemas": { "readOnly": true }, "id": { "type": "string", "readOnly": true }, "displayName": { "type": "string" }, "externalId": { "type": "string" }, "members": { "readOnly": true }, "meta": { "type": "object", "additionalProperties": {}, "readOnly": true } }, "required": [ "displayName", "id", "members", "meta", "schemas" ] }, "ScimUser": { "type": "object", "description": "Serializes a Django User to match the SCIM 2.0 User schema.", "properties": { "schemas": { "readOnly": true }, "id": { "type": "string", "readOnly": true }, "userName": { "type": "string" }, "name": { "type": "object", "additionalProperties": {}, "readOnly": true }, "emails": { "readOnly": true }, "active": { "type": "boolean" }, "meta": { "type": "object", "additionalProperties": {}, "readOnly": true } }, "required": [ "active", "emails", "id", "meta", "name", "schemas", "userName" ] }, "ServiceUsageBalanceData": { "type": "object", "properties": { "effective_limit": { "type": "integer" }, "balance_value": { "type": "integer" }, "balance_percent": { "type": "integer" }, "exceeded": { "type": "boolean" } }, "required": [ "balance_percent", "balance_value", "effective_limit", "exceeded" ] }, "ServiceUsageBalances": { "type": "object", "properties": { "submission": { "$ref": "#/components/schemas/NullableServiceUsageBalanceData" }, "storage_bytes": { "$ref": "#/components/schemas/NullableServiceUsageBalanceData" }, "asr_seconds": { "$ref": "#/components/schemas/NullableServiceUsageBalanceData" }, "mt_characters": { "$ref": "#/components/schemas/NullableServiceUsageBalanceData" }, "llm_requests": { "$ref": "#/components/schemas/NullableServiceUsageBalanceData" } }, "required": [ "asr_seconds", "llm_requests", "mt_characters", "storage_bytes", "submission" ] }, "ServiceUsageResponse": { "type": "object", "properties": { "total_nlp_usage": { "type": "object", "properties": { "asr_seconds_current_period": { "type": "integer" }, "llm_requests_current_period": { "type": "integer" }, "mt_characters_current_period": { "type": "integer" }, "asr_seconds_all_time": { "type": "integer" }, "llm_requests_all_time": { "type": "integer" }, "mt_characters_all_time": { "type": "integer" } }, "required": [ "asr_seconds_all_time", "asr_seconds_current_period", "llm_requests_all_time", "llm_requests_current_period", "mt_characters_all_time", "mt_characters_current_period" ] }, "total_storage_bytes": { "type": "integer" }, "total_submission_count": { "type": "object", "properties": { "all_time": { "type": "integer" }, "current_period": { "type": "integer" } } }, "balances": { "$ref": "#/components/schemas/ServiceUsageBalances" }, "current_period_start": { "type": "string", "format": "date-time" }, "current_period_end": { "type": "string", "format": "date-time" }, "last_updated": { "type": "string", "format": "date-time" } }, "required": [ "balances", "current_period_end", "current_period_start", "last_updated", "total_nlp_usage", "total_storage_bytes", "total_submission_count" ] }, "SocialAccount": { "type": "object", "description": "serialize allauth SocialAccounts for use with a REST API", "properties": { "provider": { "type": "string", "maxLength": 200 }, "uid": { "type": "string", "maxLength": 191 }, "last_login": { "type": "string", "format": "date-time", "readOnly": true }, "date_joined": { "type": "string", "format": "date-time", "readOnly": true }, "email": { "type": "string", "format": "email", "readOnly": true }, "username": { "type": "string", "readOnly": true } }, "required": [ "date_joined", "email", "last_login", "provider", "uid", "username" ] }, "SocialApp": { "type": "object", "properties": { "provider": { "type": "string" }, "name": { "type": "string" }, "client_id": { "type": "string" }, "provider_id": { "type": [ "string", "null" ] }, "managed": { "type": "boolean" }, "domains": { "type": "array", "items": { "type": "string" } } }, "required": [ "client_id", "domains", "managed", "name", "provider", "provider_id" ] }, "SocialAppDetail": { "type": "object", "description": "Public, display-only representation of a `SocialApp`\n\nFields are declared explicitly rather than through `ModelSerializer` so that\ncredentials (`client_id`, `secret`, `key`) and provider internals\n(`settings`, which holds `server_url`) cannot leak by accident", "properties": { "provider_id": { "type": "string", "readOnly": true }, "name": { "type": "string", "readOnly": true } }, "required": [ "name", "provider_id" ] }, "StripeIntervalEnum": { "enum": [ "day", "week", "month", "year" ], "type": "string", "description": "* `day` - Day\n* `week` - Week\n* `month` - Month\n* `year` - Year" }, "StripePriceType": { "enum": [ "one_time", "recurring" ], "type": "string", "description": "* `one_time` - One-time\n* `recurring` - Recurring" }, "StripeProductType": { "enum": [ "good", "service" ], "type": "string", "description": "* `good` - Good\n* `service` - Service" }, "StripeUsageType": { "enum": [ "metered", "licensed" ], "type": "string", "description": "* `metered` - Metered\n* `licensed` - Licensed" }, "Subscription": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionItem" } }, "schedule": { "$ref": "#/components/schemas/SubscriptionSchedule" }, "application_fee_percent": { "type": [ "string", "null" ], "format": "decimal", "pattern": "^-?\\d{0,3}(?:\\.\\d{0,2})?$" }, "djstripe_created": { "type": "string", "format": "date-time", "readOnly": true }, "djstripe_updated": { "type": "string", "format": "date-time", "readOnly": true }, "stripe_data": {}, "id": { "type": "string", "maxLength": 255 }, "livemode": { "type": [ "boolean", "null" ], "description": "Null here indicates that the livemode status is unknown or was previously unrecorded. Otherwise, this field indicates whether this record comes from Stripe test mode or live mode operation." }, "created": { "type": [ "string", "null" ], "format": "date-time", "description": "The datetime this object was created in stripe." }, "metadata": { "oneOf": [ {}, { "type": "null" } ], "description": "A set of key/value pairs that you can attach to an object. It can be useful for storing additional information about an object in a structured format." }, "description": { "type": [ "string", "null" ], "description": "A description of this object." }, "billing_cycle_anchor": { "type": [ "string", "null" ], "format": "date-time", "description": "Determines the date of the first full invoice, and, for plans with `month` or `year` intervals, the day of the month for subsequent invoices." }, "billing_thresholds": { "oneOf": [ {}, { "type": "null" } ], "description": "Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period." }, "cancel_at": { "type": [ "string", "null" ], "format": "date-time", "description": "A date in the future at which the subscription will automatically get canceled." }, "cancel_at_period_end": { "type": "boolean", "description": "If the subscription has been canceled with the ``at_period_end`` flag set to true, ``cancel_at_period_end`` on the subscription will be true. You can use this attribute to determine whether a subscription that has a status of active is scheduled to be canceled at the end of the current period." }, "canceled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "If the subscription has been canceled, the date of that cancellation. If the subscription was canceled with ``cancel_at_period_end``, canceled_at will still reflect the date of the initial cancellation request, not the end of the subscription period when the subscription is automatically moved to a canceled state." }, "collection_method": { "allOf": [ { "$ref": "#/components/schemas/CollectionMethodEnum" } ], "description": "Either `charge_automatically`, or `send_invoice`. When charging automatically, Stripe will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions.\n\n* `charge_automatically` - Charge automatically\n* `send_invoice` - Send invoice" }, "current_period_end": { "type": "string", "format": "date-time", "description": "End of the current period for which the subscription has been invoiced. At the end of this period, a new invoice will be created." }, "current_period_start": { "type": "string", "format": "date-time", "description": "Start of the current period for which the subscription has been invoiced." }, "days_until_due": { "type": [ "integer", "null" ], "maximum": 2147483647, "minimum": -2147483648, "description": "Number of days a customer has to pay invoices generated by this subscription. This value will be `null` for subscriptions where `billing=charge_automatically`." }, "discount": { "oneOf": [ {}, { "type": "null" } ], "description": "Describes the current discount applied to this subscription, if there is one. When billing, a discount applied to a subscription overrides a discount applied on a customer-wide basis." }, "ended_at": { "type": [ "string", "null" ], "format": "date-time", "description": "If the subscription has ended (either because it was canceled or because the customer was switched to a subscription to a new plan), the date the subscription ended." }, "next_pending_invoice_item_invoice": { "type": [ "string", "null" ], "format": "date-time", "description": "Specifies the approximate timestamp on which any pending invoice items will be billed according to the schedule provided at pending_invoice_item_interval." }, "pause_collection": { "oneOf": [ {}, { "type": "null" } ], "description": "If specified, payment collection for this subscription will be paused." }, "pending_invoice_item_interval": { "oneOf": [ {}, { "type": "null" } ], "description": "Specifies an interval for how often to bill for any pending invoice items. It is analogous to calling Create an invoice for the given subscription at the specified interval." }, "pending_update": { "oneOf": [ {}, { "type": "null" } ], "description": "If specified, pending updates that will be applied to the subscription once the latest_invoice has been paid." }, "proration_behavior": { "description": "Determines how to handle prorations when the billing cycle changes (e.g., when switching plans, resetting billing_cycle_anchor=now, or starting a trial), or if an item’s quantity changes\n\n* `always_invoice` - Always invoice\n* `create_prorations` - Create prorations\n* `none` - None", "oneOf": [ { "$ref": "#/components/schemas/ProrationBehaviorEnum" }, { "$ref": "#/components/schemas/BlankEnum" } ] }, "proration_date": { "type": [ "string", "null" ], "format": "date-time", "description": "If set, the proration will be calculated as though the subscription was updated at the given time. This can be used to apply exactly the same proration that was previewed with upcoming invoice endpoint. It can also be used to implement custom proration logic, such as prorating by day instead of by second, by providing the time that you wish to use for proration calculations" }, "quantity": { "type": [ "integer", "null" ], "maximum": 2147483647, "minimum": -2147483648, "description": "The quantity applied to this subscription. This value will be `null` for multi-plan subscriptions" }, "start_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date when the subscription was first created. The date might differ from the created date due to backdating." }, "status": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionStatusEnum" } ], "description": "The status of this subscription.\n\n* `active` - Active\n* `canceled` - Canceled\n* `incomplete` - Incomplete\n* `incomplete_expired` - Incomplete Expired\n* `past_due` - Past due\n* `trialing` - Trialing\n* `unpaid` - Unpaid" }, "trial_end": { "type": [ "string", "null" ], "format": "date-time", "description": "If the subscription has a trial, the end of that trial." }, "trial_start": { "type": [ "string", "null" ], "format": "date-time", "description": "If the subscription has a trial, the beginning of that trial." }, "djstripe_owner_account": { "type": [ "string", "null" ], "description": "The Stripe Account this object belongs to." }, "customer": { "type": "string", "description": "The customer associated with this subscription." }, "default_payment_method": { "type": [ "string", "null" ], "description": "The default payment method for the subscription. It must belong to the customer associated with the subscription. If not set, invoices will use the default payment method in the customer's invoice settings." }, "default_source": { "type": [ "string", "null" ], "description": "The default payment source for the subscription. It must belong to the customer associated with the subscription and be in a chargeable state. If not set, defaults to the customer's default source." }, "latest_invoice": { "type": [ "string", "null" ], "description": "The most recent invoice this subscription has generated." }, "pending_setup_intent": { "type": [ "string", "null" ], "description": "We can use this SetupIntent to collect user authentication when creating a subscription without immediate payment or updating a subscription's payment method, allowing you to optimize for off-session payments." }, "plan": { "type": [ "integer", "null" ], "title": "ID", "description": "The plan associated with this subscription. This value will be `null` for multi-plan subscriptions" }, "default_tax_rates": { "type": "array", "items": { "type": "integer", "title": "ID" }, "description": "The tax rates that will apply to any subscription item that does not have tax_rates set. Invoices created will have their default_tax_rates populated from the subscription." } }, "required": [ "application_fee_percent", "collection_method", "current_period_end", "current_period_start", "customer", "djstripe_created", "djstripe_updated", "id", "items", "schedule", "status" ] }, "SubscriptionItem": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 255 }, "price": { "$ref": "#/components/schemas/PriceWithProduct" }, "quantity": { "type": [ "integer", "null" ], "maximum": 2147483647, "minimum": 0, "description": "The quantity of the plan to which the customer should be subscribed." } }, "required": [ "id", "price" ] }, "SubscriptionSchedule": { "type": "object", "properties": { "phases": { "type": "object", "additionalProperties": {}, "readOnly": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionScheduleStatusEnum" } ], "readOnly": true, "description": "The present status of the subscription schedule. Possible values are `not_started`, `active`, `completed`, `released`, and `canceled`.\n\n* `active` - Active\n* `canceled` - Canceled\n* `completed` - Completed\n* `not_started` - Not started\n* `released` - Released" } }, "required": [ "phases", "status" ] }, "SubscriptionScheduleStatusEnum": { "enum": [ "active", "canceled", "completed", "not_started", "released" ], "type": "string", "description": "* `active` - Active\n* `canceled` - Canceled\n* `completed` - Completed\n* `not_started` - Not started\n* `released` - Released" }, "SubscriptionStatusEnum": { "enum": [ "active", "canceled", "incomplete", "incomplete_expired", "past_due", "trialing", "unpaid" ], "type": "string", "description": "* `active` - Active\n* `canceled` - Canceled\n* `incomplete` - Incomplete\n* `incomplete_expired` - Incomplete Expired\n* `past_due` - Past due\n* `trialing` - Trialing\n* `unpaid` - Unpaid" }, "SuperUserAccessLogResponse": { "type": "object", "properties": { "user": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/users/bob/" }, "date_created": { "type": "string", "format": "date-time" }, "username": { "type": "string" }, "metadata": { "type": "object", "properties": { "source": { "type": "string" }, "auth_type": { "type": "string" }, "ip_address": { "type": "string" }, "initial_user_uid": { "type": "string" }, "initial_user_username": { "type": "string" }, "authorized_app_name": { "type": "string" } } }, "user_uid": { "type": "string" }, "count": { "type": "integer" }, "action": { "type": "string" } }, "required": [ "action", "count", "date_created", "metadata", "user", "user_uid", "username" ] }, "SupplementalDataAutomaticQual": { "type": "object", "description": "Map of automatic question UUIDs to their action objects", "additionalProperties": { "$ref": "#/components/schemas/SupplementalDataAutomaticQualItem" }, "patternProperties": { "^[0-9a-fA-F-]{36}$": { "$ref": "#/components/schemas/SupplementalDataAutomaticQualItem" } } }, "SupplementalDataAutomaticQualItem": { "type": "object", "properties": { "_dateCreated": { "type": "string", "format": "date-time" }, "_dateModified": { "type": "string", "format": "date-time" }, "_versions": { "type": "array", "items": { "$ref": "#/components/schemas/SupplementalDataVersionItemQualAutomatic" }, "minLength": 1 } }, "additionalProperties": false, "required": [ "_dateCreated", "_dateModified", "_versions" ] }, "SupplementalDataAutomaticTranscription": { "type": "object", "properties": { "_dateCreated": { "type": "string", "format": "date-time" }, "_dateModified": { "type": "string", "format": "date-time" }, "_versions": { "type": "array", "items": { "$ref": "#/components/schemas/SupplementalDataVersionItemAutomatic" }, "minLength": 1 } }, "additionalProperties": false, "required": [ "_dateCreated", "_dateModified", "_versions" ] }, "SupplementalDataAutomaticTranslation": { "type": "object", "description": "Map of language codes to automatic translation objects", "additionalProperties": { "$ref": "#/components/schemas/SupplementalDataAutomaticTranslationItem" } }, "SupplementalDataAutomaticTranslationItem": { "type": "object", "properties": { "_dateCreated": { "type": "string", "format": "date-time" }, "_dateModified": { "type": "string", "format": "date-time" }, "_versions": { "type": "array", "items": { "$ref": "#/components/schemas/SupplementalDataVersionItemAutomaticWithDep" }, "minLength": 1 } }, "additionalProperties": false, "required": [ "_dateCreated", "_dateModified", "_versions" ] }, "SupplementalDataContentAutomatic": { "oneOf": [ { "$ref": "#/components/schemas/SupplementalDataContentAutomaticInProgress" }, { "$ref": "#/components/schemas/SupplementalDataContentAutomaticFailed" }, { "$ref": "#/components/schemas/SupplementalDataContentAutomaticComplete" }, { "$ref": "#/components/schemas/SupplementalDataContentAutomaticDeleted" } ] }, "SupplementalDataContentAutomaticComplete": { "type": "object", "properties": { "language": { "type": "string" }, "locale": { "type": "string" }, "status": { "type": "string", "const": "complete" }, "value": { "type": "string" } }, "additionalProperties": false, "required": [ "language", "status", "value" ] }, "SupplementalDataContentAutomaticDeleted": { "type": "object", "properties": { "language": { "type": "string" }, "locale": { "type": "string" }, "status": { "type": "string", "const": "deleted" }, "value": { "type": "null" } }, "additionalProperties": false, "required": [ "language", "status", "value" ] }, "SupplementalDataContentAutomaticFailed": { "type": "object", "properties": { "language": { "type": "string" }, "locale": { "type": "string" }, "status": { "type": "string", "const": "failed" }, "error": { "type": "string" } }, "additionalProperties": false, "required": [ "error", "language", "status" ] }, "SupplementalDataContentAutomaticInProgress": { "type": "object", "properties": { "language": { "type": "string" }, "locale": { "type": "string" }, "status": { "type": "string", "const": "in_progress" } }, "additionalProperties": false, "required": [ "language", "status" ] }, "SupplementalDataContentManual": { "type": "object", "properties": { "language": { "type": "string" }, "locale": { "type": "string" }, "value": { "type": "string", "nullable": true } }, "additionalProperties": false, "required": [ "language", "value" ] }, "SupplementalDataDependency": { "type": "object", "properties": { "_actionId": { "type": "string" }, "_uuid": { "type": "string", "format": "uuid" } }, "additionalProperties": false, "required": [ "_actionId", "_uuid" ] }, "SupplementalDataManualQual": { "type": "object", "description": "Map of manual qualitative question UUIDs to their action objects", "additionalProperties": { "$ref": "#/components/schemas/SupplementalDataManualQualItem" }, "patternProperties": { "^[0-9a-fA-F-]{36}$": { "$ref": "#/components/schemas/SupplementalDataManualQualItem" } } }, "SupplementalDataManualQualItem": { "type": "object", "properties": { "_dateCreated": { "type": "string", "format": "date-time" }, "_dateModified": { "type": "string", "format": "date-time" }, "_versions": { "type": "array", "items": { "$ref": "#/components/schemas/SupplementalDataVersionItemQual" }, "minLength": 1 } }, "additionalProperties": false, "required": [ "_dateCreated", "_dateModified", "_versions" ] }, "SupplementalDataManualTranscription": { "type": "object", "properties": { "_dateCreated": { "type": "string", "format": "date-time" }, "_dateModified": { "type": "string", "format": "date-time" }, "_versions": { "type": "array", "items": { "$ref": "#/components/schemas/SupplementalDataVersionItemManual" }, "minLength": 1 } }, "additionalProperties": false, "required": [ "_dateCreated", "_dateModified", "_versions" ] }, "SupplementalDataManualTranslation": { "type": "object", "description": "Map of language codes to manual translation objects", "additionalProperties": { "$ref": "#/components/schemas/SupplementalDataManualTranslationItem" } }, "SupplementalDataManualTranslationItem": { "type": "object", "properties": { "_dateCreated": { "type": "string", "format": "date-time" }, "_dateModified": { "type": "string", "format": "date-time" }, "_versions": { "type": "array", "items": { "$ref": "#/components/schemas/SupplementalDataVersionItemManualWithDep" }, "minLength": 1 } }, "additionalProperties": false, "required": [ "_dateCreated", "_dateModified", "_versions" ] }, "SupplementalDataQualData": { "oneOf": [ { "$ref": "#/components/schemas/DataSupplementManualQualDataInteger" }, { "$ref": "#/components/schemas/DataSupplementManualQualDataText" }, { "$ref": "#/components/schemas/DataSupplementManualQualDataSelectOne" }, { "$ref": "#/components/schemas/DataSupplementManualQualDataSelectMultiple" }, { "$ref": "#/components/schemas/DataSupplementManualQualDataTags" } ] }, "SupplementalDataQualDataAutomatic": { "oneOf": [ { "$ref": "#/components/schemas/DataSupplementAutomaticQualDataIntegerResponse" }, { "$ref": "#/components/schemas/DataSupplementAutomaticQualDataTextResponse" }, { "$ref": "#/components/schemas/DataSupplementAutomaticQualDataSelectOneResponse" }, { "$ref": "#/components/schemas/DataSupplementAutomaticQualDataSelectMultipleResponse" } ] }, "SupplementalDataResponseAction": { "type": "object", "properties": { "manual_transcription": { "$ref": "#/components/schemas/SupplementalDataManualTranscription" }, "manual_translation": { "$ref": "#/components/schemas/SupplementalDataManualTranslation" }, "automatic_google_transcription": { "$ref": "#/components/schemas/SupplementalDataAutomaticTranscription" }, "automatic_google_translation": { "$ref": "#/components/schemas/SupplementalDataAutomaticTranslation" }, "manual_qual": { "$ref": "#/components/schemas/SupplementalDataManualQual" }, "automatic_bedrock_qual": { "$ref": "#/components/schemas/SupplementalDataAutomaticQual" } }, "additionalProperties": false, "anyOf": [ { "required": [ "manual_transcription" ] }, { "required": [ "manual_translation" ] }, { "required": [ "automatic_google_transcription" ] }, { "required": [ "automatic_google_translation" ] }, { "required": [ "manual_qual" ] }, { "required": [ "automatic_bedrock_qual" ] } ] }, "SupplementalDataVersionItemAutomatic": { "type": "object", "properties": { "_dateCreated": { "type": "string", "format": "date-time" }, "_uuid": { "type": "string", "format": "uuid" }, "_dateAccepted": { "type": "string", "format": "date-time" }, "_data": { "$ref": "#/components/schemas/SupplementalDataContentAutomatic" } }, "additionalProperties": false, "required": [ "_data", "_dateCreated", "_uuid" ] }, "SupplementalDataVersionItemAutomaticWithDep": { "type": "object", "properties": { "_dateCreated": { "type": "string", "format": "date-time" }, "_uuid": { "type": "string", "format": "uuid" }, "_dateAccepted": { "type": "string", "format": "date-time" }, "_dependency": { "$ref": "#/components/schemas/SupplementalDataDependency" }, "_data": { "$ref": "#/components/schemas/SupplementalDataContentAutomatic" } }, "additionalProperties": false, "required": [ "_data", "_dateCreated", "_uuid" ] }, "SupplementalDataVersionItemManual": { "type": "object", "properties": { "_dateCreated": { "type": "string", "format": "date-time" }, "_uuid": { "type": "string", "format": "uuid" }, "_dateAccepted": { "type": "string", "format": "date-time" }, "_data": { "$ref": "#/components/schemas/SupplementalDataContentManual" } }, "additionalProperties": false, "required": [ "_data", "_dateAccepted", "_dateCreated", "_uuid" ] }, "SupplementalDataVersionItemManualWithDep": { "type": "object", "properties": { "_dateCreated": { "type": "string", "format": "date-time" }, "_uuid": { "type": "string", "format": "uuid" }, "_dateAccepted": { "type": "string", "format": "date-time" }, "_dependency": { "$ref": "#/components/schemas/SupplementalDataDependency" }, "_data": { "$ref": "#/components/schemas/SupplementalDataContentManual" } }, "additionalProperties": false, "required": [ "_data", "_dateAccepted", "_dateCreated", "_uuid" ] }, "SupplementalDataVersionItemQual": { "type": "object", "properties": { "_data": { "$ref": "#/components/schemas/SupplementalDataQualData" }, "_dateAccepted": { "type": "string", "format": "date-time" }, "_dateCreated": { "type": "string", "format": "date-time" }, "_dateVerified": { "type": "string", "format": "date-time" }, "_uuid": { "type": "string", "format": "uuid" }, "verified": { "type": "boolean" } }, "additionalProperties": false, "required": [ "_data", "_dateCreated", "_uuid" ] }, "SupplementalDataVersionItemQualAutomatic": { "type": "object", "properties": { "_data": { "$ref": "#/components/schemas/SupplementalDataQualDataAutomatic" }, "_dateAccepted": { "type": "string", "format": "date-time" }, "_dateCreated": { "type": "string", "format": "date-time" }, "_dateVerified": { "type": "string", "format": "date-time" }, "_uuid": { "type": "string", "format": "uuid" }, "_dependency": { "$ref": "#/components/schemas/SupplementalDataDependency" }, "verified": { "type": "boolean" } }, "additionalProperties": false, "required": [ "_data", "_dateCreated", "_uuid" ] }, "TagListResponse": { "type": "object", "properties": { "name": { "type": "string" }, "uid": { "type": "string" } }, "required": [ "name", "uid" ] }, "TermsOfServiceResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/terms-of-service/terms_of_service_fr/" }, "slug": { "type": "string" }, "body": { "type": "string" } }, "required": [ "body", "slug", "url" ] }, "TranscriptionService": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "code": { "type": "string", "maxLength": 10 } }, "required": [ "code", "name" ] }, "TransferListResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/project-ownership/invites/poi52fGkwDjQeZkUxcaou39q/transfers/pot54pTqM5qwKdZ4wnNdiwDY/" }, "asset": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/" }, "status": { "type": "string" }, "error": { "type": "string" }, "date_modified": { "type": "string", "format": "date-time" }, "statuses": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "status_type": { "type": "string" }, "error": { "type": "string" } } } } }, "required": [ "asset", "date_modified", "error", "status", "statuses", "url" ] }, "TranslationService": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "code": { "type": "string", "maxLength": 10 } }, "required": [ "code", "name" ] }, "UserListResponse": { "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" }, "is_superuser": { "type": "boolean" }, "date_joined": { "type": "string", "format": "date-time" }, "last_login": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "email": { "type": "string", "format": "email" }, "asset_count": { "type": "integer" }, "metadata": { "type": "object", "properties": { "name": { "type": "string" }, "sector": { "type": "string" }, "country": { "type": "string" }, "organization": { "type": "string" }, "last_ui_language": { "type": "string" }, "organization_type": { "type": "string" }, "organization_website": { "type": "string" }, "project_views_settings": { "type": "object", "properties": { "kobo_my_project": { "type": "object", "properties": { "order": { "type": "object" }, "fields": { "type": "array", "items": { "type": "string" } }, "filters": { "type": "array", "items": { "type": "string" } } } } } } } } }, "required": [ "asset_count", "date_joined", "email", "id", "is_active", "is_superuser", "last_login", "metadata", "username" ] }, "UserReportsListResponse": { "type": "object", "properties": { "user_uid": { "type": "string" }, "username": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "is_superuser": { "type": "boolean" }, "is_staff": { "type": "boolean" }, "is_active": { "type": "boolean" }, "date_joined": { "type": "string", "format": "date-time" }, "last_login": { "type": "string", "format": "date-time" }, "validated_email": { "type": "boolean" }, "mfa_is_active": { "type": "boolean" }, "sso_is_active": { "type": "boolean" }, "accepted_tos": { "type": "boolean" }, "social_accounts": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "uid": { "type": "string" }, "last_joined": { "type": "string", "format": "date-time" }, "date_joined": { "type": "string", "format": "date-time" }, "email": { "type": "string", "format": "email" }, "username": { "type": "string" } } } }, "organizations": { "type": "object", "properties": { "organization_name": { "type": "string" }, "organization_uid": { "type": "string" }, "role": { "type": "string" } } }, "extra_details": { "type": "object", "properties": { "data": { "type": "object", "properties": { "name": { "type": "string" }, "sector": { "type": "string" }, "country": { "type": "string" }, "organization": { "type": "string" }, "last_ui_language": { "type": "string" }, "organization_type": { "type": "string" }, "organization_website": { "type": "string" }, "newsletter_subscription": { "type": "boolean" } } }, "date_removed": { "type": "string", "format": "date-time" }, "validated_password": { "type": "boolean" }, "password_date_changed": { "type": "string", "format": "date-time" }, "date_removal_requested": { "type": "string", "format": "date-time" } } }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "price": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "nickname": { "type": "string" }, "currency": { "type": "string" }, "type": { "type": "string" }, "recurring": { "type": "object", "properties": { "meter": { "type": "string" }, "interval": { "type": "string" }, "usage_type": { "type": "string" }, "interval_count": { "type": "integer" }, "aggregate_usage": { "type": "string" }, "trial_period_days": { "type": "integer" } } }, "unit_amount": { "type": "integer" }, "human_readable_price": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "active": { "type": "boolean" }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "metadata": { "type": "object", "properties": { "product_type": { "type": "string" }, "storage_bytes_limit": { "type": "string" } }, "additionalProperties": true } } }, "transform_quantity": { "type": "object", "properties": { "divide_by": { "type": "integer" }, "round": { "type": "string" } }, "nullable": true } } } }, "quantity": { "type": "integer" } } } }, "schedule": { "type": "object", "properties": { "phases": { "type": "array", "items": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "plan": { "type": "string" }, "price": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "quantity": { "type": "integer" }, "tax_rates": { "type": "array", "items": { "type": "integer" } }, "billing_thresholds": { "type": "object", "additionalProperties": true } } } }, "coupon": { "type": "string" }, "currency": { "type": "string" }, "end_date": { "type": "integer" }, "metadata": { "type": "object" }, "trial_end": { "type": "integer" }, "start_date": { "type": "integer" }, "description": { "type": "string" }, "on_behalf_of": { "type": "string" }, "automatic_tax": { "type": "object", "schema": { "enabled": { "type": "boolean" } } }, "transfer_data": { "type": "string" }, "invoice_settings": { "type": "string" }, "add_invoice_items": { "type": "object" }, "collection_method": { "type": "string" }, "default_tax_rates": { "type": "object" }, "billing_thresholds": { "type": "string" }, "proration_behavior": { "type": "string" }, "billing_cycle_anchor": { "type": "integer" }, "default_payment_method": { "type": "string" }, "application_fee_percent": { "type": "integer" } }, "nullable": true } }, "status": { "type": "string" } }, "nullable": true }, "djstripe_created": { "type": "string" }, "djstripe_updated": { "type": "string" }, "id": { "type": "string" }, "livemode": { "type": "boolean" }, "created": { "type": "string" }, "metadata": { "type": "object", "properties": { "request_url": { "type": "string" }, "organization_id": { "type": "string" }, "kpi_owner_user_id": { "type": "string" }, "kpi_owner_username": { "type": "string" } } }, "description": { "type": "string" }, "application_fee_percent": { "type": "number", "format": "float" }, "billing_cycle_anchor": { "type": "string" }, "billing_thresholds": { "type": "string" }, "cancel_at": { "type": "string" }, "cancel_at_period_end": { "type": "boolean" }, "canceled_at": { "type": "string" }, "collection_method": { "type": "string" }, "current_period_end": { "type": "string" }, "current_period_start": { "type": "string" }, "days_until_due": { "type": "string" }, "discount": { "type": "string" }, "ended_at": { "type": "string" }, "next_pending_invoice_item_invoice": { "type": "string" }, "pause_collection": { "type": "string" }, "pending_invoice_item_interval": { "type": "string" }, "pending_update": { "type": "string" }, "proration_behavior": { "type": "string" }, "proration_date": { "type": "string" }, "quantity": { "type": "integer" }, "start_date": { "type": "string" }, "status": { "type": "string" }, "trial_end": { "type": "string" }, "trial_start": { "type": "string" }, "djstripe_owner_account": { "type": "string" }, "customer": { "type": "string" }, "default_payment_method": { "type": "string" }, "default_source": { "type": "string" }, "latest_invoice": { "type": "string" }, "pending_setup_intent": { "type": "string" }, "plan": { "type": "integer" }, "default_tax_rates": { "type": "object" } } } }, "service_usage": { "$ref": "#/components/schemas/UserReportsServiceUsageResponse" }, "account_restricted": { "type": "boolean" }, "asset_count": { "type": "integer" }, "active_project_count": { "type": "integer" }, "last_updated": { "type": "string", "format": "date-time" } }, "required": [ "accepted_tos", "account_restricted", "active_project_count", "asset_count", "date_joined", "email", "extra_details", "first_name", "is_active", "is_staff", "is_superuser", "last_login", "last_name", "last_updated", "mfa_is_active", "organizations", "service_usage", "social_accounts", "sso_is_active", "subscriptions", "user_uid", "username", "validated_email" ] }, "UserReportsServiceUsageResponse": { "type": "object", "properties": { "total_nlp_usage": { "type": "object", "properties": { "asr_seconds_current_period": { "type": "integer" }, "llm_requests_current_period": { "type": "integer" }, "mt_characters_current_period": { "type": "integer" }, "asr_seconds_all_time": { "type": "integer" }, "llm_requests_all_time": { "type": "integer" }, "mt_characters_all_time": { "type": "integer" } }, "required": [ "asr_seconds_all_time", "asr_seconds_current_period", "llm_requests_all_time", "llm_requests_current_period", "mt_characters_all_time", "mt_characters_current_period" ] }, "total_storage_bytes": { "type": "integer" }, "total_submission_count": { "type": "object", "properties": { "retention_days": { "type": "integer" }, "cumulative": { "type": "integer" }, "current_period": { "type": "integer" } } }, "balances": { "$ref": "#/components/schemas/ServiceUsageBalances" }, "current_period_start": { "type": "string", "format": "date-time" }, "current_period_end": { "type": "string", "format": "date-time" } }, "required": [ "balances", "current_period_end", "current_period_start", "total_nlp_usage", "total_storage_bytes", "total_submission_count" ] }, "UserRetrieveResponse": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/users/bob/" }, "username": { "type": "string" }, "date_joined": { "type": "string", "format": "date-time" }, "public_collection_subscribers_count": { "type": "integer" }, "public_collections_count": { "type": "integer" } }, "required": [ "date_joined", "public_collection_subscribers_count", "public_collections_count", "url", "username" ] }, "VersionListResponse": { "type": "object", "properties": { "uid": { "type": "string", "readOnly": true }, "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/versions/vf7pK9SmkJPYZVzr4uypi4/", "readOnly": true }, "content_hash": { "type": "string", "readOnly": true }, "date_deployed": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "boolean", "enum": [ false ] } ], "readOnly": true }, "date_modified": { "type": "string", "format": "date-time", "readOnly": true }, "version_number": { "type": "string", "readOnly": true } }, "required": [ "content_hash", "date_deployed", "date_modified", "uid", "url", "version_number" ] }, "VersionRetrieveResponse": { "type": "object", "properties": { "uid": { "type": "string", "readOnly": true }, "url": { "type": "string", "format": "uri", "example": "https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/versions/vf7pK9SmkJPYZVzr4uypi4/", "readOnly": true }, "content_hash": { "type": "string", "readOnly": true }, "date_deployed": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "boolean", "enum": [ false ] } ], "readOnly": true }, "date_modified": { "type": "string", "format": "date-time", "readOnly": true }, "version_number": { "type": "string", "readOnly": true }, "content": { "type": "object", "properties": { "schema": { "type": "string" }, "survey": { "type": "array", "items": { "type": "object", "properties": { "hint": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string" }, "$kuid": { "type": "string" }, "label": { "type": "array", "items": { "type": "string" } }, "$xpath": { "type": "string" }, "required": { "type": "boolean" }, "$autoname": { "type": "string" } } } }, "settings": { "type": "object", "properties": { "default_language": { "type": "string" } } }, "translated": { "type": "array", "items": { "type": "string" } }, "translation": { "type": "array", "items": { "type": "string" } } }, "readOnly": true } }, "required": [ "content", "content_hash", "date_deployed", "date_modified", "uid", "url", "version_number" ] }, "historyExportResponse": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] }, "Session": { "type": "object", "properties": { "user_agent": { "type": "string", "example": "Mozilla Firefox" }, "ip": { "type": "string", "example": "127.2.3.192" }, "created_at": { "$ref": "#/components/schemas/Timestamp" }, "is_current": { "type": "boolean" }, "id": { "type": "integer", "example": 123 }, "last_seen_at": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "user_agent", "ip", "created_at", "is_current", "id" ] }, "AccountConfiguration": { "type": "object", "description": "Configuration of the Django `allauth.account` app.\n", "properties": { "login_methods": { "type": "array", "items": { "type": "string", "enum": [ "email", "username" ] } }, "is_open_for_signup": { "type": "boolean" }, "email_verification_by_code_enabled": { "type": "boolean" }, "login_by_code_enabled": { "type": "boolean" }, "password_reset_by_code_enabled": { "type": "boolean" } }, "required": [ "authentication_method", "email_verification_by_code_enabled", "is_open_for_signup", "login_by_code_enabled" ] }, "AuthenticationResponse": { "type": "object", "description": "An authentication related response.\n", "properties": { "status": { "type": "integer", "enum": [ 401 ] }, "data": { "type": "object", "properties": { "flows": { "type": "array", "items": { "$ref": "#/components/schemas/Flow" } } }, "required": [ "flows" ] }, "meta": { "$ref": "#/components/schemas/AuthenticationMeta" } }, "required": [ "status", "data", "meta" ] }, "ForbiddenResponse": { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 403 ] } }, "required": [ "status" ] }, "ConflictResponse": { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 409 ] } }, "required": [ "status" ] }, "EndSessions": { "type": "object", "properties": { "sessions": { "description": "The IDs of the sessions that are to be ended.\n", "type": "array", "items": { "type": "integer", "example": 123 } } }, "required": [ "sessions" ] }, "PhoneNumber": { "type": "object", "description": "A phone number.\n", "properties": { "phone": { "type": "string", "example": "+314159265359" }, "verified": { "type": "boolean" } }, "required": [ "phone", "verified" ] }, "PhoneNumbersResponse": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/StatusOK" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumber" } } }, "required": [ "status", "data" ] }, "PhoneNumberChangeResponse": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/StatusAccepted" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumber" } } }, "required": [ "status", "data" ], "example": { "status": 202, "data": [ { "phone": "+314159265359", "verified": false } ] } }, "ReauthenticationResponse": { "type": "object", "description": "A response indicating reauthentication is required.\n", "properties": { "status": { "type": "integer", "enum": [ 401 ] }, "data": { "$ref": "#/components/schemas/ReauthenticationRequired" }, "meta": { "$ref": "#/components/schemas/AuthenticatedMeta" } }, "required": [ "status", "data", "meta" ] }, "SessionGoneResponse": { "type": "object", "description": "The session is expired or invalid.\n", "properties": { "status": { "type": "integer", "enum": [ 410 ] }, "data": { "type": "object" }, "meta": { "$ref": "#/components/schemas/AuthenticationMeta" } }, "required": [ "status", "data", "meta" ] }, "BaseAuthenticationMeta": { "type": "object", "properties": { "session_token": { "type": "string", "description": "The session token (`app` clients only).\n", "example": "ufwcig0zen9skyd545jc0fkq813ghar2" }, "access_token": { "type": "string", "description": "The access token (`app` clients only).\n", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdW" } } }, "AuthenticationMeta": { "allOf": [ { "$ref": "#/components/schemas/BaseAuthenticationMeta" }, { "type": "object", "description": "Metadata available in an authentication related response.\n", "properties": { "is_authenticated": { "type": "boolean" } }, "required": [ "is_authenticated" ] } ] }, "AuthenticatedMeta": { "allOf": [ { "$ref": "#/components/schemas/BaseAuthenticationMeta" }, { "type": "object", "description": "Metadata available in an re-authentication related response.\n", "properties": { "is_authenticated": { "type": "boolean", "enum": [ true ] } }, "required": [ "is_authenticated" ] } ] }, "Flow": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "login", "login_by_code", "mfa_authenticate", "mfa_reauthenticate", "provider_redirect", "provider_signup", "provider_token", "reauthenticate", "signup", "verify_email", "verify_phone" ] }, "provider": { "$ref": "#/components/schemas/Provider" }, "is_pending": { "type": "boolean", "enum": [ true ] }, "types": { "type": "array", "description": "Matches `settings.MFA_SUPPORTED_TYPES`.", "items": { "$ref": "#/components/schemas/AuthenticatorType" } } }, "required": [ "id" ] }, "Authenticated": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" }, "methods": { "type": "array", "description": "A list of methods used to authenticate.\n", "items": { "$ref": "#/components/schemas/AuthenticationMethod" } } }, "required": [ "user", "methods" ] }, "ReauthenticationRequired": { "properties": { "flows": { "type": "array", "items": { "$ref": "#/components/schemas/Flow" } }, "user": { "$ref": "#/components/schemas/User" }, "methods": { "type": "array", "description": "A list of methods used to authenticate.\n", "items": { "$ref": "#/components/schemas/AuthenticationMethod" } } }, "required": [ "flows", "user", "methods" ], "type": "object" }, "AuthenticationMethod": { "oneOf": [ { "type": "object", "title": "Authenticated by username/email login\n", "properties": { "method": { "type": "string", "enum": [ "password" ] }, "at": { "$ref": "#/components/schemas/Timestamp" }, "email": { "$ref": "#/components/schemas/Email" }, "username": { "$ref": "#/components/schemas/Username" } }, "required": [ "method", "at" ] }, { "type": "object", "title": "Authenticated after password reset\n", "properties": { "method": { "type": "string", "enum": [ "password_reset" ] }, "at": { "$ref": "#/components/schemas/Timestamp" }, "email": { "$ref": "#/components/schemas/Email" } }, "required": [ "at", "email", "method" ] }, { "type": "object", "title": "Authenticated by confirming a code sent by email.\n", "properties": { "method": { "type": "string", "enum": [ "code" ] }, "at": { "$ref": "#/components/schemas/Timestamp" }, "email": { "$ref": "#/components/schemas/Email" } }, "required": [ "at", "email", "method" ] }, { "type": "object", "title": "Authenticated by confirming a code sent by phone.\n", "properties": { "method": { "type": "string", "enum": [ "code" ] }, "at": { "$ref": "#/components/schemas/Timestamp" }, "phone": { "$ref": "#/components/schemas/Phone" } }, "required": [ "at", "method", "phone" ] }, { "type": "object", "title": "Reauthenticated by password\n", "properties": { "method": { "type": "string", "enum": [ "password" ] }, "at": { "$ref": "#/components/schemas/Timestamp" }, "reauthenticated": { "type": "boolean", "enum": [ true ] } }, "required": [ "method", "reauthenticated", "at" ] }, { "type": "object", "title": "Authenticated by third-party provider\n", "properties": { "method": { "type": "string", "enum": [ "socialaccount" ] }, "at": { "$ref": "#/components/schemas/Timestamp" }, "provider": { "$ref": "#/components/schemas/ProviderID" }, "uid": { "$ref": "#/components/schemas/ProviderAccountID" } }, "required": [ "method", "reauthenticated", "at", "provider", "uid" ] }, { "type": "object", "title": "(Re)authenticated by 2FA\n", "properties": { "method": { "type": "string", "enum": [ "mfa" ] }, "at": { "$ref": "#/components/schemas/Timestamp" }, "type": { "$ref": "#/components/schemas/AuthenticatorType" }, "reauthenticated": { "type": "boolean" } }, "required": [ "method", "at", "type" ] } ] }, "AuthenticatedResponse": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/StatusOK" }, "data": { "$ref": "#/components/schemas/Authenticated" }, "meta": { "$ref": "#/components/schemas/AuthenticationMeta" } }, "required": [ "status", "data", "meta" ] }, "MFAAuthenticate": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/AuthenticatorCode" } }, "required": [ "code" ] }, "MFATrust": { "type": "object", "properties": { "trust": { "type": "boolean" } }, "required": [ "trust" ] }, "ConfirmLoginCode": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/Code" } }, "required": [ "code" ] }, "ClientID": { "type": "string", "description": "The client ID (in case of OAuth2 or OpenID Connect based providers)\n", "example": "123.apps.googleusercontent.com" }, "ProviderToken": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/ProviderID" }, "process": { "$ref": "#/components/schemas/Process" }, "token": { "description": "The token.\n", "type": "object", "properties": { "client_id": { "$ref": "#/components/schemas/ClientID" }, "id_token": { "type": "string", "description": "The ID token.\n", "example": "eyJhbGciOiJI" }, "access_token": { "type": "string", "description": "The access token.\n", "example": "36POk6yJV_adQs" } }, "required": [ "client_id" ] } }, "required": [ "provider", "process", "token" ] }, "ProviderRedirect": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/ProviderID" }, "callback_url": { "type": "string", "description": "The URL to return to after the redirect flow is complete.\n\nNote that this is not to be mistaken with the callback URL that you\nconfigure over at the OAuth provider during the OAuth app/client\nsetup. The flow is as follows:\n\n 1. Your frontend redirects to the headless provider redirect\n endpoint in a synchronous (non-XHR) manner, informing allauth\n (by means of `callback_url`) where to redirect to after the\n provider handshake is completed.\n\n 2. Headless will redirect to the (OAuth) identity provider to\n initiate the handshake, passing along a different callback URL\n to the provider: one that points to an allauth backend URL.\n This is the URL that you need to have setup at your OAuth\n app/client configuration. Note that this must be a backend URL\n as providers can use POST requests to perform their callbacks,\n which is something a frontend would not be able to handle.\n\n 3. After the authorization at the provider is completed, the\n provider redirects to the *backend* allauth callback URL, which\n will then redirect back to the *frontend* callback URL.\n\n 4. Your frontend is now expected to fetch the current session to\n determine what the next course of action is. The user could be\n authenticated at this point, or another flow is pending\n (e.g. email verification, or, provider signup). In case of\n errors a `?error=` is passed to the frontend callback URL.\n", "example": "https://app.project.org/account/provider/callback" }, "process": { "$ref": "#/components/schemas/Process" } }, "required": [ "provider", "process", "callback_url" ] }, "RequestPassword": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/Email" } }, "required": [ "email" ] }, "RequestLoginCode": { "type": "object", "anyOf": [ { "title": "Request login code (phone)", "properties": { "phone": { "$ref": "#/components/schemas/Phone" } }, "required": [ "phone" ] }, { "title": "Request login code (email)", "properties": { "email": { "$ref": "#/components/schemas/Email" } }, "required": [ "email" ] } ] }, "Reauthenticate": { "type": "object", "properties": { "password": { "$ref": "#/components/schemas/Password" } }, "required": [ "password" ] }, "ProviderSignup": { "allOf": [ { "$ref": "#/components/schemas/BaseSignup" } ] }, "PasskeySignup": { "allOf": [ { "$ref": "#/components/schemas/BaseSignup" } ] }, "BaseSignup": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/Email" }, "username": { "$ref": "#/components/schemas/Username" } }, "required": [ "email", "username" ] }, "Signup": { "allOf": [ { "$ref": "#/components/schemas/BaseSignup" }, { "type": "object", "properties": { "password": { "$ref": "#/components/schemas/Password" } }, "required": [ "password" ] } ] }, "Username": { "type": "string", "description": "The username.\n", "example": "wizard" }, "Email": { "type": "string", "description": "The email address.\n", "example": "email@domain.org" }, "Phone": { "type": "string", "description": "The phone number.\n", "example": "+314159265359" }, "AccessToken": { "type": "string", "description": "The access token.\n", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdW" }, "RefreshToken": { "type": "string", "description": "The refresh token.\n", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.QV30" }, "Login": { "allOf": [ { "type": "object", "properties": { "password": { "$ref": "#/components/schemas/Password" } }, "required": [ "password" ] }, { "anyOf": [ { "title": "Login by username", "properties": { "username": { "$ref": "#/components/schemas/Username" } }, "required": [ "username" ] }, { "title": "Login by email", "properties": { "email": { "$ref": "#/components/schemas/Email" } }, "required": [ "email" ] }, { "title": "Login by phone", "properties": { "phone": { "$ref": "#/components/schemas/Phone" } }, "required": [ "phone" ] } ] } ] }, "StatusOK": { "type": "integer", "enum": [ 200 ] }, "StatusAccepted": { "type": "integer", "enum": [ 202 ] }, "AuthenticatorID": { "type": "integer", "description": "Authenticator ID.\n", "example": 123 }, "SocialAccountConfiguration": { "type": "object", "description": "Configuration of the Django `allauth.socialaccount` app.\n", "properties": { "providers": { "$ref": "#/components/schemas/ProviderList" } }, "required": [ "providers" ] }, "MFAConfiguration": { "type": "object", "description": "Configuration of the Django `allauth.mfa` app.\n", "properties": { "supported_types": { "type": "array", "description": "Matches `settings.MFA_SUPPORTED_TYPES`.\n", "items": { "$ref": "#/components/schemas/AuthenticatorType" } } }, "required": [ "supported_types" ] }, "UserSessionsConfiguration": { "type": "object", "description": "Configuration of the Django `allauth.usersessions` app.\n", "properties": { "track_activity": { "type": "boolean", "description": "Matches `settings.USERSESSIONS_TRACK_ACTIVITY`.\n" } }, "required": [ "track_activity" ] }, "ConfigurationResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/AccountConfiguration" }, "socialaccount": { "$ref": "#/components/schemas/SocialAccountConfiguration" }, "mfa": { "$ref": "#/components/schemas/MFAConfiguration" }, "usersessions": { "$ref": "#/components/schemas/UserSessionsConfiguration" } }, "required": [ "account" ] }, "status": { "$ref": "#/components/schemas/StatusOK" } }, "required": [ "status", "data" ], "example": { "status": 200, "data": { "account": { "authentication_method": "email" }, "socialaccount": { "providers": [ { "id": "google", "name": "Google", "flows": [ "provider_redirect", "provider_token" ], "client_id": "123.apps.googleusercontent.com", "openid_configuration_url": "https://accounts.google.com/.well-known/openid-configuration" } ] }, "mfa": { "supported_types": [ "recovery_codes", "totp" ] }, "usersessions": { "track_activity": false } } } }, "ResetPassword": { "type": "object", "properties": { "key": { "type": "string", "description": "The password reset key", "example": "2f-c4nqd4-e07d9bc694f9f28cd4fe92569d495333" }, "password": { "$ref": "#/components/schemas/Password" } }, "required": [ "key", "password" ] }, "VerifyEmail": { "type": "object", "properties": { "key": { "type": "string", "description": "The email verification key", "example": "2f-c4nqd4-e07d9bc694f9f28cd4fe92569d495333" } }, "required": [ "key" ] }, "VerifyPhone": { "type": "object", "properties": { "code": { "type": "string", "description": "The phone verification code", "example": "4S3H82" } }, "required": [ "code" ] }, "OptionalTimestamp": { "nullable": true, "$ref": "#/components/schemas/Timestamp" }, "Timestamp": { "type": "number", "description": "An epoch based timestamp (trivial to parse using: `new Date(value)*1000`)\n", "example": 1711555057.065702 }, "AuthenticatorCode": { "type": "string", "description": "An authenticator code.\n", "example": "314159" }, "Code": { "type": "string", "description": "An one-time code.\n", "example": "NQ3TM5" }, "AuthenticatorType": { "type": "string", "enum": [ "recovery_codes", "totp", "webauthn" ], "description": "The type of authenticator.\n" }, "Password": { "type": "string", "description": "The password.\n", "example": "Alohomora!" }, "ErrorResponse": { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 400 ], "example": 400 }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "invalid", "description": "An error code.\n" }, "param": { "type": "string", "example": "email", "description": "The name of the input parameter that was incorrect.\n" }, "message": { "type": "string", "example": "Enter a valid email address.", "description": "A human readable error message.\n" } }, "required": [ "code", "message" ] } } } }, "Process": { "type": "string", "description": "The process to be executed when the user successfully\nauthenticates. When set to `login`, the user will be logged into the\naccount to which the provider account is connected, or if no such\naccount exists, a signup will occur. If set to `connect`, the provider\naccount will be connected to the list of provider accounts for the\ncurrently authenticated user.\n", "enum": [ "login", "connect" ], "example": "login" }, "ProviderID": { "type": "string", "description": "The provider ID.\n", "example": "google" }, "ProviderAccountID": { "type": "string", "description": "The provider specific account ID.\n", "example": "goo12345" }, "User": { "type": "object", "properties": { "id": { "description": "The user ID.", "example": 123, "type": "integer" }, "display": { "description": "The display name for the user.", "example": "Magic Wizard", "type": "string" }, "email": { "description": "The email address.", "example": "email@domain.org", "type": "string" }, "has_usable_password": { "description": "Whether or not the account has a password set.", "example": true, "type": "boolean" }, "username": { "description": "The username.", "example": "wizard", "type": "string" } }, "required": [ "display", "has_usable_password", "username" ] }, "BaseAuthenticator": { "type": "object", "properties": { "last_used_at": { "$ref": "#/components/schemas/OptionalTimestamp" }, "created_at": { "$ref": "#/components/schemas/Timestamp" } }, "required": [ "created_at", "last_used_at" ] }, "TOTPAuthenticator": { "allOf": [ { "$ref": "#/components/schemas/BaseAuthenticator" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "totp" ] } }, "required": [ "type" ] } ] }, "WebAuthnAuthenticator": { "allOf": [ { "$ref": "#/components/schemas/BaseAuthenticator" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "webauthn" ] }, "id": { "$ref": "#/components/schemas/AuthenticatorID" }, "name": { "type": "string", "example": "Master key" }, "is_passwordless": { "type": "boolean", "description": "Whether or not this authenticator represents a passkey. Absent if it is not specified.\n" } }, "required": [ "type", "id", "name" ] } ] }, "RecoveryCodesAuthenticator": { "allOf": [ { "$ref": "#/components/schemas/BaseAuthenticator" }, { "type": "object", "properties": { "type": { "type": "string", "description": "The authenticator type.\n", "enum": [ "recovery_codes" ] }, "total_code_count": { "type": "integer", "description": "The total number of recovery codes that initially were available.\n", "example": 10 }, "unused_code_count": { "type": "integer", "description": "The number of recovery codes that are unused.\n", "example": 7 } }, "required": [ "type", "total_code_count", "unused_code_count" ] } ] }, "SensitiveRecoveryCodesAuthenticator": { "allOf": [ { "$ref": "#/components/schemas/RecoveryCodesAuthenticator" }, { "type": "object", "properties": { "unused_codes": { "type": "array", "description": "The list of unused codes.\n", "items": { "$ref": "#/components/schemas/AuthenticatorCode" } } }, "required": [ "unused_codes" ] } ] }, "AuthenticatorList": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/TOTPAuthenticator" }, { "$ref": "#/components/schemas/RecoveryCodesAuthenticator" }, { "$ref": "#/components/schemas/WebAuthnAuthenticator" } ] } }, "ProviderList": { "type": "array", "items": { "$ref": "#/components/schemas/Provider" } }, "Provider": { "type": "object", "properties": { "id": { "type": "string", "example": "google", "description": "The provider ID.\n" }, "name": { "type": "string", "description": "The name of the provider.\n", "example": "Google" }, "client_id": { "type": "string", "description": "The client ID (in case of OAuth2 or OpenID Connect based providers)\n", "example": "123.apps.googleusercontent.com" }, "openid_configuration_url": { "type": "string", "description": "The OIDC discovery or well-known URL (in case of OAuth2 or OpenID Connect based providers)\n", "example": "https://accounts.google.com/.well-known/openid-configuration" }, "flows": { "type": "array", "description": "The authentication flows the provider integration supports.\n", "items": { "type": "string", "enum": [ "provider_redirect", "provider_token" ] } } }, "required": [ "id", "name", "flows" ] }, "ProviderAccount": { "type": "object", "properties": { "uid": { "$ref": "#/components/schemas/ProviderAccountID" }, "display": { "type": "string", "description": "A name derived from the third-party provider account data.\n", "example": "Wizzkid" }, "provider": { "$ref": "#/components/schemas/Provider" } }, "required": [ "uid", "provider", "display" ] }, "EmailVerificationInfo": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/StatusOK" }, "data": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/Email" }, "user": { "$ref": "#/components/schemas/User" } }, "required": [ "email", "user" ] }, "meta": { "type": "object", "properties": { "is_authenticating": { "type": "boolean" } }, "required": [ "is_authenticating" ] } }, "required": [ "status", "data", "meta" ] }, "WebAuthnCredentialRequestOptions": { "type": "object", "properties": { "request_options": { "type": "object", "example": { "status": 200, "data": { "request_options": { "publicKey": { "challenge": "aOecJJtLA2e-Dj2WU-zbRoJewbQqSUPxoA9EzsUL72o", "rpId": "localhost", "allowCredentials": [], "userVerification": "preferred" } } } } } }, "required": [ "request_options" ] }, "WebAuthnCredentialCreationOptions": { "type": "object", "properties": { "creation_options": { "type": "object", "example": { "status": 200, "data": { "request_options": { "publicKey": { "challenge": "aOecJJtLA2e-Dj2WU-zbRoJewbQqSUPxoA9EzsUL72o", "rpId": "localhost", "allowCredentials": [], "userVerification": "preferred" } } } } } }, "required": [ "creation_options" ] }, "WebAuthnCredential": { "type": "object", "example": { "credential": { "type": "public-key", "id": "-J4JNfPfnLyRSMK4R...", "rawId": "-J4JNfPfnLyRSMK4R...", "authenticatorAttachment": "cross-platform", "response": { "clientDataJSON": "eyJjaGFsbGVuZ2UiOi...", "authenticatorData": "SZYN5YgO...", "signature": "MEUCIE-7sqILygPqGbrRZ4j2nqeqUU...", "userHandle": "Mg..." }, "clientExtensionResults": {} } } } }, "securitySchemes": { "BasicAuth": { "type": "http", "scheme": "basic" }, "ScimAuth": { "type": "http", "scheme": "bearer", "description": "Authentication via SCIM API Key provided in the Authorization header as a Bearer token." }, "TokenAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Token-based authentication. Use the format: `Token `" } }, "examples": { "User": { "value": { "id": 123, "display": "Magic Wizard", "email": "email@domain.org", "has_usable_password": true, "username": "wizard" } }, "AuthenticatedByPassword": { "summary": "Authenticated by password.\n", "value": { "status": 200, "data": { "user": { "id": 123, "display": "Magic Wizard", "email": "email@domain.org", "has_usable_password": true, "username": "wizard" }, "methods": [ { "method": "password", "at": 1711555057.065702, "email": "email@domain.org" } ] }, "meta": { "is_authenticated": true, "session_token": "ufwcig0zen9skyd545jc0fkq813ghar2", "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdW" } } }, "AuthenticatedByCode": { "summary": "Authenticated by code.\n", "value": { "status": 200, "data": { "user": { "id": 123, "display": "Magic Wizard", "email": "email@domain.org", "has_usable_password": true, "username": "wizard" }, "methods": [ { "method": "code", "at": 1711555057.065702, "email": "email@domain.org" } ] }, "meta": { "is_authenticated": true, "session_token": "ufwcig0zen9skyd545jc0fkq813ghar2", "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdW" } } }, "AuthenticatedByPasswordAnd2FA": { "summary": "Fully authenticated using by password and 2FA.\n", "value": { "status": 200, "data": { "user": { "id": 123, "display": "Magic Wizard", "email": "email@domain.org", "has_usable_password": true, "username": "wizard" }, "methods": [ { "method": "password", "at": 1711555057.065702, "email": "email@domain.org" }, { "method": "mfa", "at": 1711555060.9375854, "id": 66, "type": "totp" } ] }, "meta": { "is_authenticated": true, "session_token": "ufwcig0zen9skyd545jc0fkq813ghar2", "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdW" } } }, "CannotGenerateRecoveryCodes": { "summary": "Unable to generate recovery codes.\n", "value": { "status": 400, "errors": [ { "message": "You cannot deactivate two-factor authentication.\ncode: cannot_generate_recovery_codes\n" } ] } }, "DisconnectNotAllowedNoPassword": { "summary": "Account without a password.", "value": { "status": 400, "errors": [ { "message": "Your account has no password set up.", "code": "no_password", "param": "account" } ] } }, "DisconnectNotAllowedNoVerifiedEmail": { "summary": "Account without a verified email.", "value": { "status": 400, "errors": [ { "message": "Your account has no verified email address.", "code": "no_verified_email", "param": "account" } ] } }, "InvalidAuthenticatorCode": { "summary": "An error response indicating that the provided code is incorrect.\n", "value": { "status": 400, "errors": [ { "message": "Incorrect code.", "code": "incorrect_code", "param": "code" } ] } }, "InvalidEmailVerificationKey": { "summary": "Email verification key invalid.\n", "value": { "status": 400, "errors": [ { "message": "Invalid or expired key.", "code": "invalid", "param": "key" } ] } }, "InvalidEmail": { "value": { "status": 400, "errors": [ { "message": "Enter a valid email address.", "code": "invalid", "param": "email" } ] } }, "IncorrectPassword": { "value": { "status": 400, "errors": [ { "message": "Incorrect password.", "param": "password", "code": "incorrect_password" } ] } }, "InvalidPasswordResetKey": { "summary": "Password reset key invalid.\n", "value": { "status": 400, "errors": [ { "message": "The password reset token was invalid.", "code": "token_invalid", "param": "key" } ] } }, "InvalidProviderToken": { "summary": "Provider token invalid.\n", "value": { "status": 400, "errors": [ { "message": "The token was invalid.", "code": "invalid", "param": "token" } ] } }, "PasswordMismatch": { "value": { "status": 400, "errors": [ { "message": "The email address and/or password you specified are not correct.", "code": "email_password_mismatch", "param": "password" } ] } }, "UnauthenticatedInitial": { "summary": "Unauthenticated: Initial\n", "value": { "status": 401, "data": { "flows": [ { "id": "login" }, { "id": "signup" }, { "id": "provider_redirect", "providers": [ "facebook", "google", "telegram" ] }, { "id": "provider_token", "providers": [ "google" ] } ] }, "meta": { "is_authenticated": false } } }, "UnauthenticatedPending2FA": { "summary": "Unauthenticated: pending 2FA\n", "value": { "status": 401, "data": { "flows": [ { "id": "login" }, { "id": "signup" }, { "id": "provider_redirect", "providers": [ "facebook", "google", "telegram" ] }, { "id": "provider_token", "providers": [ "google" ] }, { "id": "mfa_authenticate", "is_pending": true } ] }, "meta": { "is_authenticated": false } } }, "UnauthenticatedPendingLoginByCode": { "summary": "Unauthenticated: pending login by code\n", "value": { "status": 401, "data": { "flows": [ { "id": "login" }, { "id": "signup" }, { "id": "provider_redirect", "providers": [ "facebook", "google", "telegram" ] }, { "id": "provider_token", "providers": [ "google" ] }, { "id": "mfa_authenticate" }, { "id": "login_by_code", "is_pending": true } ] }, "meta": { "is_authenticated": false } } }, "UnauthenticatedPendingProviderSignup": { "summary": "Unauthenticated: pending provider signup\n", "value": { "status": 401, "data": { "flows": [ { "id": "login" }, { "id": "signup" }, { "id": "provider_redirect", "providers": [ "facebook", "google", "telegram" ] }, { "id": "provider_token", "providers": [ "google" ] }, { "id": "provider_signup", "provider": { "id": "google", "name": "Google", "client_id": "123.apps.googleusercontent.com", "flows": [ "provider_redirect", "provider_token" ] }, "is_pending": true } ] }, "meta": { "is_authenticated": false } } }, "UnauthenticatedPendingEmailVerification": { "summary": "Unauthenticated: pending email verification\n", "value": { "status": 401, "data": { "flows": [ { "id": "login" }, { "id": "signup" }, { "id": "provider_redirect", "providers": [ "facebook", "google", "telegram" ] }, { "id": "provider_token", "providers": [ "google" ] }, { "id": "verify_email", "is_pending": true } ] }, "meta": { "is_authenticated": false } } }, "ReauthenticationRequired": { "summary": "Reauthentication required\n", "value": { "status": 401, "data": { "user": { "id": 123, "display": "Magic Wizard", "email": "email@domain.org", "has_usable_password": true, "username": "wizard" }, "methods": [ { "method": "password", "at": 1711555057.065702, "email": "email@domain.org" }, { "method": "mfa", "at": 1711555060.9375854, "id": 66, "type": "totp" } ], "flows": [ { "id": "reauthenticate" }, { "id": "mfa_reauthenticate" } ] }, "meta": { "is_authenticated": true } } } }, "requestBodies": { "Login": { "description": "Login.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Login" } } } }, "LoginWebAuthn": { "description": "Login using WebAuthn.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "$ref": "#/components/schemas/WebAuthnCredential" } }, "required": [ "credential" ] } } } }, "ReauthenticateWebAuthn": { "description": "Reauthenticate using WebAuthn.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "$ref": "#/components/schemas/WebAuthnCredential" } }, "required": [ "credential" ] } } } }, "AuthenticateWebAuthn": { "description": "Authenticate using WebAuthn.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "$ref": "#/components/schemas/WebAuthnCredential" } }, "required": [ "credential" ] } } } }, "MFAAuthenticate": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MFAAuthenticate" } } } }, "MFATrust": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MFATrust" } } } }, "ConfirmLoginCode": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmLoginCode" } } } }, "EndSessions": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndSessions" } } } }, "PasskeySignup": { "description": "Signup using a passkey", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeySignup" } } } }, "ProviderAccount": { "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "$ref": "#/components/schemas/ProviderID" }, "account": { "$ref": "#/components/schemas/ProviderAccountID" } }, "required": [ "account", "provider" ] } } } }, "ProviderRedirect": { "required": true, "description": "Initiate the provider redirect flow.\n", "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ProviderRedirect" } } } }, "ProviderSignup": { "description": "Provider signup.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderSignup" } } } }, "ProviderToken": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderToken" } } } }, "Reauthenticate": { "description": "Reauthenticate.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reauthenticate" } } } }, "RefreshToken": { "content": { "application/json": { "schema": { "type": "object", "properties": { "refresh_token": { "$ref": "#/components/schemas/RefreshToken" } }, "required": [ "refresh_token" ] } } } }, "RequestPassword": { "description": "Request password.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestPassword" } } } }, "RequestLoginCode": { "description": "Request a login code.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestLoginCode" } } } }, "SetupTOTP": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/AuthenticatorCode" } }, "required": [ "code" ] } } } }, "Signup": { "description": "Signup", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Signup" } } } }, "ChangePassword": { "content": { "application/json": { "schema": { "type": "object", "properties": { "current_password": { "$ref": "#/components/schemas/Password" }, "new_password": { "type": "string", "description": "The current password.\n", "example": "Aberto!" } }, "required": [ "new_password" ] } } } }, "Email": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/Email" } }, "required": [ "email" ] } } } }, "MarkPrimaryEmail": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "An email address.\n", "example": "email@domain.org" }, "primary": { "type": "boolean", "enum": [ true ], "description": "Primary flag.\n" } }, "required": [ "email", "primary" ] } } } }, "Phone": { "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "example": "+314159265359" } }, "required": [ "phone" ] } } } }, "ResetPassword": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPassword" } } } }, "VerifyEmail": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmail" } } } }, "VerifyPhone": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyPhone" } } } }, "UpdateWebAuthn": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/AuthenticatorID" }, "name": { "type": "string", "example": "Master key" } } } } } }, "AddWebAuthnAuthenticator": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Master key" }, "credential": { "$ref": "#/components/schemas/WebAuthnCredential" } }, "required": [ "credential" ] } } } }, "DeleteWebAuthn": { "content": { "application/json": { "schema": { "type": "object", "properties": { "authenticators": { "description": "The IDs of the authenticator that are to be deleted.\n", "type": "array", "items": { "$ref": "#/components/schemas/AuthenticatorID" } } }, "required": [ "authenticators" ] } } } } }, "parameters": { "Client": { "name": "client", "in": "path", "description": "The type of client accessing the API.", "required": true, "schema": { "type": "string", "enum": [ "app", "browser" ] } }, "EmailVerificationKey": { "in": "header", "name": "X-Email-Verification-Key", "schema": { "type": "string" }, "required": true, "description": "The email verification key" }, "PasswordResetKey": { "in": "header", "name": "X-Password-Reset-Key", "schema": { "type": "string" }, "required": true, "description": "The password reset key" }, "SessionToken": { "in": "header", "name": "X-Session-Token", "required": false, "description": "Session token. Only needed when `client` is equal to `app`.\n", "schema": { "type": "string" } }, "PasswordLess": { "in": "query", "name": "passwordless", "required": false, "schema": { "type": "boolean" }, "allowEmptyValue": true, "description": "When present (regardless of its value), enables passwordless sign-in via a WebAuthn credential (Passkey),\nbut may enforce additional multi-factor authentication (MFA) requirements. Omit the parameter to disable.\n" } }, "responses": { "AddAuthenticatorConflict": { "description": "The account prohibits adding an authenticator, e.g. because of an unverified email address.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictResponse" } } } }, "Authentication": { "description": "Not authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationResponse" }, "examples": { "unauthenticated_initial": { "$ref": "#/components/examples/UnauthenticatedInitial" }, "unauthenticated_pending_2fa": { "$ref": "#/components/examples/UnauthenticatedPending2FA" }, "unauthenticated_pending_provider_signup": { "$ref": "#/components/examples/UnauthenticatedPendingProviderSignup" }, "unauthenticated_pending_email_verification": { "$ref": "#/components/examples/UnauthenticatedPendingEmailVerification" }, "reauthentication_required": { "$ref": "#/components/examples/ReauthenticationRequired" } } } } }, "Authenticators": { "description": "List of authenticators.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/StatusOK" }, "data": { "$ref": "#/components/schemas/AuthenticatorList" } }, "required": [ "status", "data" ] } } } }, "AuthenticatedByPassword": { "description": "Authenticated by password.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticatedResponse" }, "examples": { "authenticated": { "$ref": "#/components/examples/AuthenticatedByPassword" } } } } }, "AuthenticatedByCode": { "description": "Authenticated by code.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticatedResponse" }, "examples": { "authenticated": { "$ref": "#/components/examples/AuthenticatedByCode" } } } } }, "AuthenticatedByPasswordAnd2FA": { "description": "Authenticated by password and 2FA.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticatedResponse" }, "examples": { "authenticated": { "$ref": "#/components/examples/AuthenticatedByPasswordAnd2FA" } } } } }, "AuthenticationOrReauthentication": { "description": "The response indicates authentication or re-authentication is required.\n", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AuthenticationResponse" }, { "$ref": "#/components/schemas/ReauthenticationResponse" } ] } } } }, "Configuration": { "description": "The django-allauth configuration.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationResponse" } } } }, "EmailAddresses": { "description": "List of email addresses.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/StatusOK" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAddress" } } }, "required": [ "status", "data" ] } } } }, "EmailVerificationInfo": { "description": "Email verification information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationInfo" } } } }, "Error": { "description": "An input error occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "A forbidden response.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenResponse" } } } }, "NotFound": { "description": "Not found.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 404 ] } }, "required": [ "status" ] } } } }, "PasswordResetInfo": { "description": "Information about the password reset key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/StatusOK" }, "data": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } } } }, "required": [ "status", "data" ] } } } }, "PhoneNumbers": { "description": "List of phone numbers.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumbersResponse" } } } }, "ProviderAccounts": { "description": "List of third-party provider accounts.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/StatusOK" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderAccount" } } }, "required": [ "status", "data" ] } } } }, "ProviderSignup": { "description": "Information relating to the pending provider signup.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/StatusOK" }, "data": { "type": "object", "properties": { "email": { "type": "array", "items": { "$ref": "#/components/schemas/EmailAddress" } }, "account": { "$ref": "#/components/schemas/ProviderAccount" }, "user": { "$ref": "#/components/schemas/User" } }, "required": [ "email", "account", "user" ] } }, "required": [ "status", "data" ] } } } }, "ReauthenticationRequired": { "description": "The response indicates reauthentication is required.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReauthenticationResponse" }, "examples": { "reauthentication_required": { "summary": "Reauthentication required\n", "value": { "status": 401, "data": { "user": { "id": 123, "display": "Magic Wizard", "email": "email@domain.org", "has_usable_password": true, "username": "wizard" }, "methods": [ { "method": "password", "at": 1711555057.065702, "email": "email@domain.org" }, { "method": "mfa", "at": 1711555060.9375854, "id": 66, "type": "totp" } ], "flows": [ { "id": "reauthenticate" }, { "id": "mfa_reauthenticate" } ] }, "meta": { "is_authenticated": true } } } } } } }, "RecoveryCodes": { "description": "Information on the recovery codes.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/StatusOK" }, "data": { "$ref": "#/components/schemas/SensitiveRecoveryCodesAuthenticator" } }, "required": [ "status", "data" ] } } } }, "RefreshToken": { "description": "A new access token (and optionally new refresh token).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/StatusOK" }, "data": { "type": "object", "properties": { "access_token": { "$ref": "#/components/schemas/AccessToken" }, "refresh_token": { "$ref": "#/components/schemas/RefreshToken" } }, "required": [ "access_token" ] } }, "required": [ "data", "status" ] } } } }, "Sessions": { "description": "List of sessions.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/StatusOK" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Session" } } }, "required": [ "status", "data" ] } } } }, "SessionGone": { "description": "The response indicates session is invalid or no longer exists.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionGoneResponse" }, "examples": { "unauth": { "$ref": "#/components/examples/UnauthenticatedInitial" } } } } }, "StatusOK": { "description": "A success response.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/StatusOK" } }, "required": [ "status" ] } } } }, "TooManyRequests": { "description": "Too many requests.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 429 ] } }, "required": [ "status" ] } } } }, "TOTPAuthenticator": { "description": "Information on the TOTP authenticator.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/StatusOK" }, "meta": { "properties": { "recovery_codes_generated": { "description": "Whether or not recovery codes where generated automatically.", "type": "boolean" } }, "type": "object" }, "data": { "$ref": "#/components/schemas/TOTPAuthenticator" } }, "required": [ "status", "data" ] } } } }, "TOTPAuthenticatorNotFound": { "description": "No TOTP authenticator has been set up.\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "enum": [ 404 ] }, "meta": { "type": "object", "properties": { "secret": { "type": "string", "description": "A TOTP secret that can be used to setup a new authenticator.\n", "example": "J4ZKKXTK7NOVU7EPUVY23LCDV4T2QZYM" }, "totp_url": { "type": "string", "description": "otpauth URI from which a QR code can be generated and scanned by OTP clients.\n", "example": "otpauth://totp/Example:alice@fsf.org?secret=JBSWY3DPEHPK3PXP&issuer=Example" } }, "required": [ "secret", "totp_url" ] } }, "required": [ "status", "meta" ] } } } }, "Unauthenticated": { "description": "There is no authenticated session.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationResponse" }, "examples": { "unauth": { "$ref": "#/components/examples/UnauthenticatedInitial" } } } } }, "Authenticated": { "description": "The user is authenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticatedResponse" } } } }, "WebAuthnRequestOptionsResponse": { "description": "WebAuthn credential request options.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/StatusOK" }, "data": { "$ref": "#/components/schemas/WebAuthnCredentialRequestOptions" } }, "required": [ "status", "data" ] } } } }, "WebAuthnCreationOptionsResponse": { "description": "WebAuthn credential creation options.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/StatusOK" }, "data": { "$ref": "#/components/schemas/WebAuthnCredentialCreationOptions" } }, "required": [ "status", "data" ] } } } }, "WebAuthnAuthenticator": { "description": "A WebAuthn authenticator.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/StatusOK" }, "data": { "$ref": "#/components/schemas/WebAuthnAuthenticator" } }, "required": [ "status", "data" ] } } } }, "AddWebAuthnAuthenticator": { "description": "A WebAuthn authenticator.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/StatusOK" }, "data": { "$ref": "#/components/schemas/WebAuthnAuthenticator" }, "meta": { "type": "object", "properties": { "recovery_codes_generated": { "type": "boolean", "description": "Whether or not recovery codes where generated automatically.\n" } } } }, "required": [ "status", "data", "meta" ] } } } } } }, "tags": [ { "name": "Manage projects and library content", "description": [ "Create, organize, and manage projects, assets (projects/library content), and tags" ] }, { "name": "Form content", "description": "Export and preview assets (projects/library content) in different formats" }, { "name": "Survey data", "description": "View, edit, validate, export, and report collected data" }, { "name": "Survey data - Rest Services", "description": "Configure and manage webhooks for survey data integrations" }, { "name": "Manage permissions", "description": "Assign, clone, and bulk-manage project and asset (projects/library content) permissions" }, { "name": "Logging", "description": "Project history logs, access logs, Rest Service hook logs" }, { "name": "Library collections", "description": "Subscribe to and manage shared library collections" }, { "name": "Server logs (superusers)", "description": "View server-wide logs" }, { "name": "User / team / organization / usage", "description": "Manage users, orgs, invites, roles, and usage tracking" }, { "name": "Other", "description": "Languages, available permissions, other" } ] }