openapi: 3.0.3 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/). The 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. **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 ⚠️ _Only available to superusers_ Submissions will be grouped together by user by hour **Filterable fields:** - date_created - user_uid - user__username - metadata__source - metadata__auth_type - metadata__ip_address **Some examples:** 1. All logs from a specific IP address `api/v2/access-logs/?q=metadata__ip_address:"127.0.0.1"` 2. All logs created after Jan 1, 2025 `api/v2/access-logs/?q=date_created__gte:"2025-01-01"` *Notes: Do not forget to wrap search terms in double-quotes if they contain spaces (e.g. date and time "2022-11-15 20:34")* 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 ⚠️ _Only available to superusers_ 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 ⚠️ _Only available to superusers_ 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 Submissions will be grouped together by hour Results from this endpoint can be filtered by a boolean query specified in the `q` parameter. **Filterable fields:** * date_created * metadata__source * metadata__auth_type * metadata__ip_address **Some examples:** * All logs from a specific IP address `api/v2/access-logs/?q=metadata__ip_address:"127.0.0.1"` * All logs created after Jan, 1 2025 `api/v2/access-logs/?q=date_created__date__gte:"2025-01-01"` *Notes: Do not forget to wrap search terms in double-quotes if they contain spaces (e.g. date and time "2022-11-15 20:34")* 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 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 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 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 When creating an asset snapshot, you must provide either: - the asset (as a URI), or - the source (as a JSON object representing the asset) …but not both. 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/ErrorObject' examples: BadRequest: value: detail: 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 Note: If the `Content-Type` of the request is set to `application/xml`, the response will return the XML version of the form, rather than the JSON representation of the asset snapshot. 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 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 Returns a `302 Found` redirect to the Enketo preview page associated with the asset. 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. It is useful for debugging pyxform transformations 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 This endpoint is used by Enketo to fetch and return the full XML form. It behaves like the standard retrieve endpoint but includes an additional `` node containing the disclaimer, if one exists. 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 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 Create a subscription to a public collection for the user. 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/ErrorObject' examples: BadRequest: value: detail: 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 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 Unsubscribe from a public asset. 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 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 Search can be made with `q` parameter. Search filters can be returned with results by passing `metadata=on` to querystring. Results can be sorted with `ordering` parameter, e.g.: ```shell curl -X GET https://kf.kobotoolbox.org/api/v2/assets/?ordering=-name ``` Allowed fields are: - `asset_type` - `date_modified` - `date_deployed` - `date_modified__date` - `date_deployed__date` - `name` - `settings__sector` - `settings__sector__value` - `settings__description` - `owner__username` - `owner__extra_details__data__name` - `owner__extra_details__data__organization` - `owner__email` - `_deployment_status` - `subscribers_count` Note: Collections can be displayed first with parameter `collections_first`, e.g.: ```shell curl -X GET https://kf.kobotoolbox.org/api/v2/assets/?collections_first=true&ordering=-name ``` 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 When cloning an asset, you must provide: - the name (as a string), - the `clone_from` (the uid representing the asset), - the asset_type Where `asset_type` must be one of these values: * block (can be cloned to `block`, `question`, `survey`, `template`) * question (can be cloned to `question`, `survey`, `template`) * survey (can be cloned to `block`, `question`, `survey`, `template`) * template (can be cloned to `survey`, `template`) Settings are cloned only when type of assets are `survey` or `template`. In that case, `share-metadata` is not preserved. When creating a new `block` or `question` asset, settings are not saved either. 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/ErrorObject' examples: BadRequest: value: detail: 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 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 Updates a project or connect project's data from this project to other projects When `Data sharing`: `fields`: Optional. List of questions whose responses will be shared. If missing or empty, all responses will be shared. Questions must be identified by full group path separated by slashes, e.g. `group/subgroup/question_name`. 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/ErrorObject' examples: BadRequest: value: detail: field_name: - Error message summary: Bad request description: '' delete: operationId: api_v2_assets_destroy description: | ## Delete a user's asset 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 Lists 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. 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: * `manual_transcription` * `manual_translation` * `automatic_google_transcription` * `automatic_google_translation` 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: * `qualText` * `qualInteger` * `qualNote` * `qualTags` 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 Enables a new type of advanced action on a question in the asset. * `action`, `params`, and `question_xpath` are required * `params` must match the expected param_schema of the `action` Accepted `action`s include: * `manual_transcription` * `automatic_google_transcription` * `manual_translation` * `automatic_google_translation` * `manual_qual` 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: * `manual_transcription` * `manual_translation` * `automatic_google_transcription` * `automatic_google_translation` 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: * `qualText` * `qualInteger` * `qualNote` * `qualTags` 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/ErrorObject' examples: BadRequest: value: detail: 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 Gets the params for one advanced action for one question in an asset 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: * `manual_transcription` * `manual_translation` * `automatic_google_transcription` * `automatic_google_translation` 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: * `qualText` * `qualInteger` * `qualNote` * `qualTags` 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 Update the params of an advanced action on a question in the asset. `params` are always additive. That means that if you PATCH a feature with a new param array, the new ones will be added to the existing ones. You cannot delete a param via the API. In the case of NLP actions, this means you can only add languages, not delete. In the case of QA analysis questions, you should send the full set questions and choices in the desired order. Any existing choices or questions in the existing params not present in the new ones will be marked as deleted, but not actually removed from the data. Deleted questions and choices will be placed at the end of the relevant list. * `params` is required * `params` must match the expected param_schema of the action being updated 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: * `manual_transcription` * `manual_translation` * `automatic_google_transcription` * `automatic_google_translation` 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: * `qualText` * `qualInteger` * `qualNote` * `qualTags` 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: * `manual_transcription` * `manual_translation` * `automatic_google_transcription` * `automatic_google_translation` 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: * `qualText` * `qualInteger` * `qualNote` * `qualTags` 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/ErrorObject' examples: BadRequest: value: detail: 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 Returns paginated bulk processing jobs associated with the specified asset. Each job is organized around one action, one question, and many submissions. Use this endpoint to monitor recently-created bulk transcription and translation jobs. Each result includes the parent job status, per-submission statuses, the original deterministic params, the user who created the job, cancellation metadata, and integer `progress` from `0` to `100`. Optional query params: * `status`: Filter by parent job status. Accepts a comma-separated list, for example `status=pending,in_progress`. * `submission_uuid`: Return only jobs that include this submission. * `question_xpath`: Return only jobs for this question xpath. Job statuses: * `pending`: the job exists but has not started. * `in_progress`: one or more child submissions are still active. * `complete`: every child submission has reached a terminal state. * `cancelled`: the job was cancelled. Child submission statuses: * `pending` * `in_progress` * `complete` * `failed` * `cancelled` 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 Creates and starts a bulk processing job for one question across multiple submissions. Supported actions: * `automatic_google_transcription` * `automatic_google_translation` The request must include the target `question_xpath`, the submission root UUIDs to process, and deterministic `params`. `params.language` is required. For transcription, `params.locale` may also be supplied when a more specific Google Speech locale is needed. Creation is atomic. If any selected submission is unknown, already has matching results, or already has an active matching bulk action, no job or child items are created. The response is the created job. Its initial status is `in_progress` because creation immediately starts background processing. 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/ErrorObject' examples: BadRequest: value: detail: 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 Returns detailed information about a single bulk processing job, including its current status, per-submission status, processing params, creator, cancellation metadata, timestamps, and integer `progress` from `0` to `100`. The response shape is identical to the item returned by the bulk job creation endpoint and to each item in the paginated list response. 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 Cancels a single bulk processing job for an asset. This endpoint currently only supports cancellation. Request body: ```json { "status": "cancelled" } ``` Cancellation is idempotent. Cancelling an already-cancelled job returns the current cancelled job. Completed jobs cannot be cancelled. When a job is cancelled, pending and in-progress child items are marked `cancelled`; terminal child items are not modified. The response is the updated job, including `cancelled_by`. 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 * `id` can only be the uid of attachment to be deleted 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/ErrorObject' examples: BadRequest: value: detail: 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 ```curl curl -X POST https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/attachments/audio-duration/ ``` > **Payload** > > { > "attachment_uids": [ > "attXXXXXXXXXXXXXXXXX", > "attYYYYYYYYYYYYYYYYY" > ] > } * Where: `attachment_uids` (required) is a list of attachment UIDs whose audio duration to retrieve. Maximum 200 UIDs per request. > **Response** > > { > "attachments": [ > { "uid": "attXXXXXXXXXXXXXXXXX", "seconds": 42 }, > { "uid": "attYYYYYYYYYYYYYYYYY", "seconds": null } > ], > "total": 42 > } * `attachments` - one entry per recognised, accessible UID in the order submitted. Unrecognised or inaccessible UIDs are silently omitted. * `seconds` - integer duration, or `null` when `ffprobe` could not determine the duration (corrupt file, unsupported format, etc.). * `total` - sum of all non-null `seconds` values. ### Batching and timeouts `ffprobe` takes approximately 0.5 s per file. With a 120 s nginx timeout, sending more than ~200 files per request risks a **504 Gateway Timeout**. * Submit files in small batches from the front-end. * Retry on 504 - already-processed attachments will be served from the db, so subsequent attempts complete faster. * Requests exceeding 200 UIDs are rejected immediately with **400 Bad Request**. 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 ```curl curl -X DELETE https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/attachments/bulk/ ``` > **Payload** > > { > "submission_root_uuids": [ > "3ed2e8de-b493-4367-a78d-3463687239dc", > "ef18fe33-c71d-4638-84d6-dafcbd69c327" > ] > } * Where: "submission_root_uuids" (required) is a list of submission root uuids on the asset to delete > **Response** > > { > "message": "{number_of_attachment} attachments deleted" > } * Where: "number_of_attachment" is the number of items that was deleted ### !! 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. !! 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/ErrorObject' examples: BadRequest: value: detail: 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. 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 Returns up to the last 31 days of daily counts and total counts of submissions to a survey. Use the `days` query to get the daily counts from the last x amount of days. Default amount is 30 days ```shell curl -X GET https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/counts/?days=7 ``` 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 By default, JSON format is used, but XML and GeoJSON are also available: ```shell curl -X GET https://kf.kobotoolbox.org/api/v2/assets/{uid}/data/ ``` ### Pagination Two parameters can be used to control pagination. * `start`: Index (zero-based) from which the results start * `limit`: Number of results per page Maximum results per page cannot exceed **1000**, unless changed by server configuration ```shell curl -X GET https://kf.kobotoolbox.org/api/v2/assets/{uid}/data/?start=0&limit=10 ``` ### Query submitted data Provides a list of submitted data for a specific form. Use `query` parameter to apply form data specific, see http://docs.mongodb.org/manual/reference/operator/query/. For more details see API Parameters. ```shell curl -X GET https://kf.kobotoolbox.org/api/v2/assets/{uid}/data/?query={"__version__": "vWvkKzNE8xCtfApJvabfjG"} curl https://kf.kobotoolbox.org/api/v2/assets/{uid}/data/?query={"_submission_time": {"$gt": "2019-09-01T01:02:03"}} ``` ### About the GeoJSON format Requesting the `geojson` format returns a `FeatureCollection` where each submission is a `Feature`. If your form has multiple geographic questions, use the `geo_question_name` query parameter to determine which question's responses populate the `geometry` for each `Feature`; otherwise, the first geographic question is used. All question/response pairs are included in the `properties` of each `Feature`, but _repeating groups are omitted_. Question types are mapped to GeoJSON geometry types as follows: * `geopoint` to `Point`; * `geotrace` to `LineString`; * `geoshape` to `Polygon`. ### ⚠️ Note: DRF-Spectacular Limitation Due 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. This 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. We’ve still included the header to show supported formats, but keep in mind: **Only `application/json` will be used in the docs UI.** 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 `{id}` can be: - The primary key of the submission - Its `_uuid` 1 - Its `rootUuid` (without "uuid:" prefix) 1 Please note that using the `_uuid` may match **several** submissions, only the first match will be returned. It is also possible to specify the format. ```shell curl -X GET https://kf.kobotoolbox.org/api/v2/assets/{uid_asset}/data/{id}.xml curl -X GET https://kf.kobotoolbox.org/api/v2/assets/{uid_asset}/data/{id}.json ``` or ```shell curl -X GET https://kf.kobotoolbox.org/api/v2/assets/{uid_asset}/data/{id}/?format=xml curl -X GET https://kf.kobotoolbox.org/api/v2/assets/{uid_asset}/data/{id}/?format=json ``` ### ⚠️ Note: DRF-Spectacular Limitation Due 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. This 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. We’ve still included the header to show supported formats, but keep in mind: **Only `application/json` will be used in the docs UI.** 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 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 Duplicates the data of a submission `{id}` can be: - The primary key of the submission - Its `_uuid` 1 - Its `rootUuid` (without "uuid:" prefix) 1 Please note that using the `_uuid` may match **several** submissions, only the first match will be returned. 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 `{id}` can be: - The primary key of the submission - Its `_uuid` 1 - Its `rootUuid` (without "uuid:" prefix) 1 Please note that using the `_uuid` may match **several** submissions, only the first match will be returned. Note: Some variation of this url exists: `/api/v2/assets/{uid_asset}/data/{id}/edit/`: deprecated, use the next one. `/api/v2/assets/{uid_asset}/data/{id}/enketo/edit/`: return the url of the enketo submission (as seen in the response example). `/api/v2/assets/{uid_asset}/data/{id}/enketo/redirect/edit/`: redirect to the enketo url submission with a 302 HTTP code. 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 `{id}` can be: - The primary key of the submission - Its `_uuid` 1 - Its `rootUuid` (without "uuid:" prefix) 1 Please note that using the `_uuid` may match **several** submissions, only the first match will be returned. Note: Some variation of this url exists: `/api/v2/assets/{uid_asset}/data/{id}/edit/`: deprecated, use the next one. `/api/v2/assets/{uid_asset}/data/{id}/enketo/edit/`: return the url of the enketo submission (as seen in the response example). `/api/v2/assets/{uid_asset}/data/{id}/enketo/redirect/edit/`: redirect to the enketo url submission with a 302 HTTP code. 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 `{id}` can be: - The primary key of the submission - Its `_uuid` 1 - Its `rootUuid` (without "uuid:" prefix) 1 Please note that using the `_uuid` may match **several** submissions, only the first match will be returned. Note: Some variation of this url exists: `/api/v2/assets/{uid_asset}/data/{id}/edit/`: deprecated, use the next one. `/api/v2/assets/{uid_asset}/data/{id}/enketo/edit/`: return the url of the enketo submission (as seen in the response example). `/api/v2/assets/{uid_asset}/data/{id}/enketo/redirect/edit/`: redirect to the enketo url submission with a 302 HTTP code. 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 `{id}` can be: - The primary key of the submission - Its `_uuid` 1 - Its `rootUuid` (without "uuid:" prefix) 1 Please note that using the `_uuid` may match **several** submissions, only the first match will be returned. Note: Some variation of this url exists: `/api/v2/assets/{uid_asset}/data/{id}/enketo/view/`: return the url of the enketo submission (as seen in the response example). `/api/v2/assets/{uid_asset}/data/{id}/enketo/redirect/view/`: redirect to the enketo url submission with a 302 code. 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 `{id}` can be: - The primary key of the submission - Its `_uuid` 1 - Its `rootUuid` (without "uuid:" prefix) 1 Please note that using the `_uuid` may match **several** submissions, only the first match will be returned. Note: Some variation of this url exists: `/api/v2/assets/{uid_asset}/data/{id}/enketo/view/`: return the url of the enketo submission (as seen in the response example). `/api/v2/assets/{uid_asset}/data/{id}/enketo/redirect/view/`: redirect to the enketo url submission with a 302 code. 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 Retrieves the validation status of a submission. 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 The 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: - `validation_status_approved` - `validation_status_not_approved` - `validation_status_on_hold` 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 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 This endpoint allows you to retrieve supplementary data attached to a submission. The supplementary data may include: * NLP actions * Manual transcription * Manual translation * Automatic Google transcription * Automatic Google translation * Qualitative analysis - manual or automatic with Bedrock * Text * Number * Single Choice * Multiple Choice * Qualitative analysis (manual only) * Tags ⚠️ The response examples in this documentation show each action in isolation for readability. In practice, multiple actions can be combined for the same question, and a single submission may contain multiple questions. 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/ErrorObject' examples: BadRequest: value: detail: field_name: - Error message summary: Bad request description: '' patch: operationId: api_v2_assets_data_supplement_partial_update description: | ## Update submission supplementary data This endpoint allows you to add, update, or delete supplementary data for a submission. It supports the same action types as the GET endpoint: * NLP actions (manual and automatic transcription / translation) * Qualitative analysis (manual and automatic) The PATCH payload follows the same per-question structure as the GET response. To delete a submission supplement, you need to PATCH the submission supplement with the appropriate null or empty value. ⚠️ In this documentation, request and response examples present each action in isolation for clarity. In practice, multiple actions may be combined within the same payload or response, including for the same question, and a single submission may contain multiple questions. 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` Set `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/ErrorObject' examples: BadRequest: value: detail: 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 * `uid_data` can be the primary key of the submission or its `uuid`. Please note that using the `uuid` may match **several** submissions, only the first match will be returned. Use the `xpath` property to retrieve an attachment. ```curl curl -X GET https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/data/451/attachment/?xpath=Upload_a_file ``` ### Get an MP3 file from an audio or video file Convert audio and video files. Only conversions to MP3 is supported for this feature ```curl curl -X GET https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/data/451/attachment/?xpath=Upload_a_file&format=mp3 ``` 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/ErrorObject' examples: BadRequest: value: detail: 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 * `uid_data` can be the primary key of the submission or its `uuid`. Please note that using the `uuid` may match **several** submissions, only the first match will be returned. * `id` of attachment can be the primary key of the attachment or its `uid`. Both examples works: ```curl curl -X GET https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/data/451/attachment/1/ ``` Or, using the `UID`: ```curl curl -X GET https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/data/451/attachment/attwYwGxdtQPSqgmHk6wS6E6/ ``` ### Get an MP3 file from an audio or video file Convert audio and video files. Only conversions to MP3 is supported for this feature ```curl curl -X GET https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/data/451/attachment/1/?format=mp3 ``` 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/ErrorObject' examples: BadRequest: value: detail: 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) Available formats: - `small` - `medium` - `large` `id` of attachment can be the primary key of the attachment or its `uid`. Both examples works: ```curl curl -X GET https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/data/451/attachment/1/small/ ``` Or, using the `UID`: ```curl curl -X GET https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/data/451/attachment/attwYwGxdtQPSqgmHk6wS6E6/medium/ ``` 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 Where `` is a string and should be an existing XML field value of the submissions. If `` is part of a group or nested group, the field must follow the group hierarchy structure, i.e.: If the field is within a group called `group_1`, the field name is `question_1` and the new value is `new value`, the payload should contain an item with the following structure: *"group_1/question_1": "new value"* Similarly, if there are `N` nested groups, the structure will be: *"group_1/sub_group_1/.../sub_group_n/question_1": "new value"* 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 ```curl curl -X DELETE https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/data/bulk/ ``` **Payload** ```json { "submissions_ids": [ 1, 2 ] } ``` * Where: `submissions_ids` (required) is a list of submission root id on the data to delete **Response** ```json { "detail": "{number_of_submissions} submissions have been deleted" } ``` * Where: `number_of_submissions` is the number of items that was deleted _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._ 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 Accepts transcription or translation results for multiple submissions in a single request. This is the bulk counterpart of the per-submission acceptance flow: instead of visiting each submission individually, users can select multiple submissions and approve all of them at once. The `operation` field declares the operation to perform. Currently only `"accept"` is supported. ### Transcription example ```json { "submission_uids": ["", ""], "question_xpath": "group_name/audio_question", "action_id": "automatic_google_transcription", "operation": "accept" } ``` ### Translation example For translation actions the `language` field is **required**: ```json { "submission_uids": ["", ""], "question_xpath": "group_name/audio_question", "action_id": "automatic_google_translation", "language": "fr", "operation": "accept" } ``` ### Response Returns the number of submission records that were successfully accepted. Submissions without a completed NLP result for the given question/action are silently skipped and excluded from the count. ```json { "accepted_count": 472 } ``` 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/ErrorObject' examples: BadRequest: value: detail: 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 * Where: "submissions_ids" (required) is a list of submission root id on the data to delete * Where: "validation_status.uid" (required) is a string and can be one of these values: * `validation_status_approved` * `validation_status_not_approved` * `validation_status_on_hold` Will return the number of submission updated as such: > **Response** > > { > "detail": "{number_of_submissions} submissions have been updated" > } 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 ```curl curl -X DELETE https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/data/validation_statuses/ ``` **Payload** ```json { "payload": { "submission_ids": [ 1, 2 ], "validation_status.uid": "validation_status" } } ``` * Where: "submissions_ids" (required) is a list of submission root id on the data to delete The 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: - `validation_status_approved` - `validation_status_not_approved` - `validation_status_on_hold` **Response** ```json { "detail": "{number_of_submissions} submissions have been updated" } ``` _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._ 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) 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 Deploy a new form or re-deploy an existing one. 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/ErrorObject' examples: BadRequest: value: detail: field_name: - Error message summary: Bad request description: '' patch: operationId: api_v2_assets_deployment_partial_update description: | ## (Un)Archive the existing deployment. Update the `active` field of the existing deployment. To overwrite the entire deployment (including the form contents), use a PUT request. 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/ErrorObject' examples: BadRequest: value: detail: 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 * _Required permissions: `view_submissions` (View submissions)_ 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 * _Required permissions: `manage_asset` (Manage project)_ Where: * `name` (required) is the name of the export setting displayed in the UI * `export_settings` (required) is a map of defined settings containing the following valid options: * `fields` (optional) is an array of column names to be included in the export (including their group hierarchy). Valid inputs include: * An array containing any string value that matches the XML column name * An empty array which will result in all columns being included * If `fields` is not included in the `export_settings`, all columns will be included in the export * `flatten` (optional) is a boolean value and only relevant when exporting to `geojson` format. * `fields_from_all_versions` (required) is a boolean to specify whether fields from all form versions will be included in the export. * `group_sep` (required) is a value used to separate the names in a hierarchy of groups. Valid inputs include: * Non-empty value * `hierarchy_in_labels` (required) is a boolean to specify whether the group hierarchy will be displayed in labels * `multiple_select` (required) is a value to specify the display of multiple-select-type responses. Valid inputs include: * `both`, * `summary`, or * `details` * `type` (required) specifies the export format. Valid export formats include: * `csv`, * `geojson`, * `spss_labels`, or * `xls` * `xls_types_as_text` (optional) is a boolean value that defaults to `false` and only affects `xls` export types. * `include_media_url` (optional) is a boolean value that defaults to `false` and only affects `xls` and `csv` export types. * `submission_ids` (optional) is an array of submission ids that will filter exported submissions to only the specified array of ids. Valid inputs include: * An array containing integer values * An empty array (no filtering) * `query` (optional) is a JSON object containing a Mongo filter query for filtering exported submissions. Valid inputs include: * A JSON object containing a valid Mongo query * An empty JSON object (no filtering) **Note that the following behaviour can be expected when specifying a value for the `multiple_select` field:** * `summary`: Includes one column per question, with all selected choices separated by spaces; * `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; * `both`: Includes the format of `summary` _and_ `details` in the export 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/ErrorObject' examples: BadRequest: value: detail: 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 * _Required permissions: `view_submissions` (View submissions)_ 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 * _Required permissions: `manage_asset` (Manage project)_ 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/ErrorObject' examples: BadRequest: value: detail: field_name: - Error message summary: Bad request description: '' delete: operationId: api_v2_assets_export_settings_destroy description: |+ ## Delete current export setting * _Required permissions: `manage_asset` (Manage project)_ 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 To retrieve data synchronously in CSV and XLSX format according to a particular instance of export settings. Processing time of synchronous exports is substantially limited compared to asynchronous exports, which are available at `/api/v2/assets/{asset_uid}/exports/`. 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/ErrorObject' examples: BadRequest: value: detail: 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 Lists the export tasks accessible to requesting user, for anonymous access nothing is returned. * _Required permissions: `view_submissions` (View submissions)_ Otherwise, the search can be more specific: **Exports matching `uid`s:** ```shell curl -X GET https://kf.kobotoolbox.org/api/v2/assets/{asset_uid}/exports/?q=uid__in:ehZUwRctkhp9QfJgvEWGg OR uid__in:ehZUwRctkhp9QfJgvDnjud ``` 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 Where: * `fields_from_all_versions` (required) is a boolean to specify whether fields from all form versions will be included in the export. * `group_sep` (required) is a value used to separate the names in a hierarchy of groups. Valid inputs include: * Non-empty value * `hierarchy_in_labels` (required) is a boolean to specify whether the group hierarchy will be displayed in labels * `lang` (required) is a string that can be set to: * `_xml` to have XML values and headers, or * Any translation specified in the form such as `English (en)`, etc. * `multiple_select` (required) is a value to specify the display of `multiple_select-type` responses. Valid inputs include: * `both`, * `summary`, or * `details` * "`type`" (required) specifies the export format. Valid export formats include: * `csv`, * `geojson`, * `spss_labels`, or * `xls` * `fields` (optional) is an array of column names to be included in the export (including their group hierarchy). Valid inputs include: * An array containing any string value that matches the XML column name * An empty array which will result in all columns being included * If `fields` is not included in the `export_settings`, all columns will be included in the export * `flatten` (optional) is a boolean value and only relevant when exporting to "geojson" format. * `xls_types_as_text` (optional) is a boolean value that defaults to `false` and only affects `xls` export types. * `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. * `submission_ids` (optional) is an array of submission ids that will filter exported submissions to only the specified array of ids. Valid inputs include: * An array containing integer values * An empty array (no filtering) * `query` (optional) is a JSON object containing a Mongo filter query for filtering exported submissions. Valid inputs include: * A JSON object containing a valid Mongo query * An empty JSON object (no filtering) 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/ErrorObject' examples: BadRequest: value: detail: 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 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 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 Results can be narrowed down with a filter by type: ```shell curl -X GET https://kf.kobotoolbox.org/api/v2/assets/aSAvYreNzVEkrWg5Gdcvg/files/?collections_first=true&ordering=-name ``` 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 Fields: - `asset` (required) - `user` (required) - `description` (required) - `file_type` (required) - `content` (as binary) (optional) - `metadata` JSON (optional) _Notes:_ 1. Files can have different types: - `map_layer` - `form_media` 2. Files can be created with three different ways - `POST` a file with `content` parameter - `POST` a base64 encoded string with `base64Encoded` parameter1 - `POST` an URL with `metadata` parameter2 1) `metadata` becomes mandatory and must contain `filename` property
2) `metadata` becomes mandatory and must contain `redirect_url` property **Files with `form_media` type must have unique `filename` per asset** 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/ErrorObject' examples: BadRequest: value: detail: 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 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 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 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 Lists all project history logs for a single project. ⚠️ _Required permissions: `manage_asset` (Manage project)_ Results from this endpoint can be filtered by a Boolean query specified in the `q` parameter. ### Filterable fields for all project history logs: - date_created - user_uid - user__username - user__email - user__is_superuser - metadata__source - metadata__ip_address - metadata__log_subtype - available subtypes: "project", "permission" ### action available actions: - add-media - add-submission - allow-anonymous-submissions - archive - clone-permissions - connect-project - delete-media - delete-service - delete-submission - deploy - disable-sharing - disallow-anonymous-submissions - disconnect-project - enable-sharing - export - modify-imported-fields - modify-qa-data - modify-service - modify-sharing - modify-submission - modify-user-permissions - redeploy - register-service - replace-form - share-data-publicly - share-form-publicly - transfer - unarchive - unshare-data-publicly - unshare-form-publicly - update-content - update-name - update-settings - update-qa ### Filterable fields by action: add-media - metadata__asset-file__uid - metadata__asset-file__filename add-submission - metadata__submission__submitted_by - metadata__submission__root_uuid archive - metadata__latest_version_uid clone-permissions - metadata__cloned_from connect-project - metadata__paired-data__source_uid - metadata__paired-data__source_name delete-media - metadata__asset-file__uid - metadata__asset-file__filename delete-service - metadata__hook__uid - metadata__hook__endpoint - metadata__hook__active delete-submission - metadata__submission__submitted_by - metadata__submission__root_uuid deploy - metadata__latest_version_uid - metadata__latest_deployed_version_uid disconnect-project - metadata__paired-data__source_uid - metadata__paired-data__source_name modify-imported-fields - metadata__paired-data__source_uid - metadata__paired-data__source_name modify-qa-data - metadata__submission__submitted_by - metadata__submission__root_uuid modify-service - metadata__hook__uid - metadata__hook__endpoint - metadata__hook__active modify-submission - metadata__submission__submitted_by - metadata__submission__root_uuid - metadata__submission__status (only present if changed) modify-user-permissions - metadata__permissions__username redeploy - metadata__latest_version_uid - metadata__latest_deployed_version_uid register-service - metadata__hook__uid - metadata__hook__endpoint - metadata__hook__active transfer - metadata__username unarchive - metadata__latest_version_uid update-name - metadata__name__old - metadata__name__new update-settings - metadata__settings__description__old - metadata__settings__description__new This endpoint can be paginated with 'start' and 'limit' parameters. 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. 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 Exports the project's history and sends it by email to the requesting user. 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 Lists the external services endpoints accessible to requesting user 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. Where: * `name` and `endpoint` are required * `active` is True by default * `export_type` must be one of these values: 1. `json` (_default_) 2. `xml` * `email_notification` is a boolean. If true, User will be notified when request to remote server has failed. * `auth_level` must be one of these values: 1. `no_auth` (_default_) 2. `basic_auth` * `subset_fields` is the list of fields of the form definition. Only these fields should be present in data sent to remote server * `settings`.`custom_headers` is dictionary of `custom header`: `value` For example: > "settings": { > "customer_headers": { > "Authorization" : "Token 1af538baa9045a84c0e889f672baf83ff24" > } * `payload_template` is a custom wrapper around `%SUBMISSION%` when sending data to remote server. It can be used only with JSON submission format. For example: > "payload_template": '{"fields": %SUBMISSION%}' 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/ErrorObject' examples: BadRequest: value: detail: 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 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. 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/ErrorObject' examples: BadRequest: value: detail: field_name: - Error message summary: Bad request description: '' delete: operationId: api_v2_assets_hooks_destroy description: | ## Delete an external service. 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 ⚠️ The `page` query parameter is deprecated, use `start` and `limit` instead. Where: * `asset_uid` - is the unique identifier of a specific asset * `hook_uid` - is the unique identifier of a specific external service * `uid` - is the unique identifier of a specific log Use the `status` query parameter to filter logs by numeric status: * `status=0`: hook has failed after exhausting all retries * `status=1`: hook is still pending * `status=2`: hook has succeeded Use the `start_date` and `end_date` query parameters to filter logs by date range, providing ISO-8601 date strings (e.g. '2022-01-14', '2022-01-21 06:51:04', '2022-01-21T06:51:08.144004+02:00'). Time zone is assumed to be UTC. If provided, it needs to be in '+00:00' format ('Z' is not supported). Watch out for url encoding for the '+' character (%2B). Note that `start_date` is inclusive, while `end_date` is exclusive. 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 * `1` - pending * `3` - processing * `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 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 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 **This call is asynchronous. Job is sent to Celery to be run in background** It returns all logs `uid`s that are being retried. 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 This endpoint is paginated and accepts these parameters: - `offset`: The initial index from which to return the results - `limit`: Number of results to return per page 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 * `fields`: Optional. List of questions whose responses will be retrieved from the source data. If missing or empty, all responses will be retrieved. Questions must be identified by full group path separated by slashes, e.g. `group/subgroup/question_name`. * `filename`: Must be unique among all asset files. Only accepts letters, numbers and '-'. 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/ErrorObject' examples: BadRequest: value: detail: 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 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 _Notes: `source` cannot be changed_ 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/ErrorObject' examples: BadRequest: value: detail: field_name: - Error message summary: Bad request description: '' delete: operationId: api_v2_assets_paired_data_destroy description: | ## Remove a connection between two projects 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 Creates the endpoints - /api/v2/assets//paired-data//external/ - /api/v2/assets//paired-data//external.xml/ 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 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.B.: - Filters use Mongo Query Engine to narrow down results - Filters are joined with `OR` operator - Implied permissions will be also assigned. (e.g. `change_asset` will add `view_asset` too) 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/ErrorObject' examples: BadRequest: value: detail: 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 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 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 * Can put both regular and partial permission in the payload 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/ErrorObject' examples: BadRequest: value: detail: field_name: - Error message summary: Bad request description: '' delete: operationId: api_v2_assets_permission_assignments_bulk_destroy description: | ## Remove all permission assignments ⚠️ **Warning** This endpoint currently supports deleting **only the user whose username is provided as a parameter**. Deletion of other accounts is not yet supported. **Payload** ```json { "username": "bob" } ``` _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._ 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/ErrorObject' examples: BadRequest: value: detail: 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 Where `clone_from` is the source uid. 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/ErrorObject' examples: BadRequest: value: detail: 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 Lists the tag values previously submitted for a `qualTags` question on this asset, sorted alphabetically. 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 Returns the submission data for all deployments of a survey. This data is grouped by answers, and does not show the data for individual submissions. The 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. 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 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: | 
#survey

                    | type    | name       | label      | default   | required   |
                    |---------+------------+------------+-----------+------------|
                    | start   | start      |            |           |            |
                    | end     | end        |            |           |            |
                    | text    | Question_1 | Question 1 |           | true       |
                    | integer | Question_2 | Question 2 |           | false      |
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 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 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 Returns the details of an asset version 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. It is useful for debugging pyxform transformations 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: |+ Project 1 EXAMPLE This is an example Example 1 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 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: | 
#survey

                    | type    | name       | label      | default   | required   |
                    |---------+------------+------------+-----------+------------|
                    | start   | start      |            |           |            |
                    | end     | end        |            |           |            |
                    | text    | Question_1 | Question 1 |           | true       |
                    | integer | Question_2 | Question 2 |           | false      |
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 Actions available: - `archive` - `delete` - `unarchive` - `undelete` (superusers only) 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 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. Useful to detect any changes in assets with only one call to `API` 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 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 Returns a paginated list of assets visible to the current user, including only `uid`, `name`, and `deployment_status` (`draft`, `deployed`, or `archived`). Use the `q` query parameter to filter by asset type (e.g. `?q=asset_type:survey`). Responses do not include a `count` field. Use the `next` and `previous` links to paginate through results. 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. ⚠️ _Only available to superusers_ Results from this endpoint can be filtered by a Boolean query specified in the `q` parameter. **Filterable fields:** * app_label * model_name * action Available actions: * create * delete * in-trash * put-back * remove * update * auth * log_type Available log types: * access * project-history * data-editing * submission-management * user-management * asset-management * date_created * user_uid * user__username * user__email * user__is_superuser * metadata__asset_uid * metadata__auth_type *Notes: Some logs may have additional filterable fields in the metadata* **Some examples:** * All deleted submissions `api/v2/audit-logs/?q=action:delete` * All deleted submissions of a specific project `aTJ3vi2KRGYj2NytSzBPp7` `api/v2/audit-logs/?q=action:delete AND metadata__asset_uid:aTJ3vi2KRGYj2NytSzBPp7` * All submissions deleted by a specific user `my_username` `api/v2/audit-logs/?q=action:delete AND user__username:my_username` * All deleted submissions submitted after a specific date `/api/v2/audit-logs/?q=action:delete AND date_created__gte:2022-11-15` * All deleted submissions submitted after a specific date **and time** `/api/v2/audit-logs/?q=action:delete AND date_created__gte:"2022-11-15 20:34"` * All authentications from superusers `api/v2/audit-logs/?q=action:auth AND user__is_superuser:True` *Notes: Do not forget to wrap search terms in double-quotes if they contain spaces (e.g. date and time "2022-11-15 20:34")* 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/environment/: get: operationId: api_v2_environment_retrieve description: | Retrieve Kobo server environment configurations. This endpoint provides a wide range of configuration details required by the frontend client, including: - Legal, support, and community URLs (e.g. Terms of Service, Privacy Policy). - Frontend configuration (retry times, usage limit enforcement, etc). - Global static lists (sectors, countries, interface languages, operational purposes). - Metadata configuration (available project and user metadata fields). - Features configurations (MFA, password entropy meter, custom guidance text). - Additional integrations and features (Stripe public key, ASR & MT enablement, Social apps). 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 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 _**Note**: this endpoint is expecting a multipart/form-data_ tags: - Manage projects and library content requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/ImportCreateRequest' required: true 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/ErrorObject' examples: BadRequest: value: detail: field_name: - Error message summary: Bad request description: '' /api/v2/imports/{uid_import}/: get: operationId: api_v2_imports_retrieve description: | ## Retrieve imported files 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. Search can be made with `q` parameter. By default, search for the term in language names or language codes. Examples: ```shell curl -X GET https://kf.kobotoolbox.org/api/v2/languages/?q=fr ``` Complex searches can be done on other fields, such as `transcription_services` and `translation_services`. Examples: ```shell curl -X GET https://kf.kobotoolbox.org/api/v2/languages/?q=transcription_services__code:goog AND translation_services__code:goog ``` Results are order by `featured` first (descending order), then by their name. 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 * `code` - is the unique identifier of a specific language 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 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 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 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/ErrorObject' examples: BadRequest: value: detail: 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 Tracks the total usage of each asset for the user in the given organization 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: 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 This endpoint returns all assets associated with a specific organization. The assets listed here are restricted to those owned by the specified organization. Only the owner or administrators of the organization can access this endpoint. ### Additional Information For more details, please refer to `/api/v2/assets/`. 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 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 Returns a paginated list of assets owned by the organization, including only `uid`, `name`, and `deployment_status` (`draft`, `deployed`, or `archived`). Use the `q` query parameter to filter by asset type (e.g. `?q=asset_type:survey`). Responses do not include a `count` field. Use the `next` and `previous` links to paginate through results. 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 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 * Create organization invites for registered and unregistered users. * Set the role for which the user is being invited - (Choices: `member`, `admin`). Default is `member`. 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/ErrorObject' examples: BadRequest: value: detail: 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 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 * Update an organization invite to accept, decline, cancel, expire, or resend. * Update the role of the invitee to `admin` or `member`. Only the owner or admin can update the role. 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/ErrorObject' examples: BadRequest: value: detail: field_name: - Error message summary: Bad request description: '' delete: operationId: api_v2_organizations_invites_destroy description: | ## Delete Organization Invite * Organization owner or admin can delete an organization invite. 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 Retrieves all members in the specified 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 - 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 Retrieves the details of a specific member within an organization by username. 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 Updates the role of a member within the organization to `admin` or `member`. - **admin**: Grants the member admin privileges within the organization - **member**: Revokes admin privileges, setting the member as a regular user 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/ErrorObject' examples: BadRequest: value: detail: field_name: - Error message summary: Bad request description: '' delete: operationId: api_v2_organizations_members_destroy description: | ## Remove Member Delete an organization member. 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 - Tracks the total usage of different services for each account in an organization - Tracks the submissions and NLP seconds/characters for the current month/year/all time - Tracks the current total storage used - Includes a detailed list of balances relative to a user's usage limits - If no organization is found with the provided ID, returns the usage for the logged-in user **This endpoint is cached for an amount of time determined by ENDPOINT_CACHE_DURATION** 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` The `implied` property of a given permission shows which additional permissions are automatically granted when assigning that particular permission. The `contradictory` property shows which permissions are removed when assigning that particular permission. 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 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. ⚠️_Only available to superusers_ Results from this endpoint can be filtered by a Boolean query specified in the `q` parameter. **Filterable fields for all project history logs:** * date_created * user_uid * user__username * user__email * user__is_superuser * metadata__source * metadata__ip_address * metadata__asset_uid * metadata__log_subtype * available subtypes: "project", "permission" * action available actions: > add-media > add-submission > allow-anonymous-submissions > archive > clone-permissions > connect-project > delete-media > delete-service > delete-submission > deploy > disable-sharing > disallow-anonymous-submissions > disconnect-project > enable-sharing > export > modify-imported-fields > modify-qa-data > modify-service > modify-sharing > modify-submission > modify-user-permissions > redeploy > register-service > replace-form > share-data-publicly > share-form-publicly > transfer > unarchive > unshare-data-publicly > unshare-form-publicly > update-content > update-name > update-settings > update-qa **Filterable fields by action:** * add-media a. metadata__asset-file__uid b. metadata__asset-file__filename * add-submission a. metadata__submission__submitted_by b. metadata__submission__root_uuid * archive a. metadata__latest_version_uid * clone-permissions a. metadata__cloned_from * connect-project a. metadata__paired-data__source_uid b. metadata__paired-data__source_name * delete-media a. metadata__asset-file__uid b. metadata__asset-file__filename * delete-service a. metadata__hook__uid b. metadata__hook__endpoint c. metadata__hook__active * delete-submission a. metadata__submission__submitted_by b. metadata__submission__root_uuid * deploy a. metadata__latest_version_uid b. metadata__latest_deployed_version_uid * disconnect-project a. metadata__paired-data__source_uid b. metadata__paired-data__source_name * modify-imported-fields a. metadata__paired-data__source_uid b. metadata__paired-data__source_name * modify-qa-data a. metadata__submission__submitted_by b. metadata__submission__root_uuid * modify-service a. metadata__hook__uid b. metadata__hook__endpoint c. metadata__hook__active * modify-submission a. metadata__submission__submitted_by b. metadata__submission__root_uuid b. metadata__submission__status (only present if changed) * modify-user-permissions a. metadata__permissions__username * redeploy a. metadata__latest_version_uid b. metadata__latest_deployed_version_uid * register-service a. metadata__hook__uid b. metadata__hook__endpoint c. metadata__hook__active * transfer a. metadata__username * unarchive a. metadata__latest_version_uid * update-name a. metadata__name__old b. metadata__name__new * update-settings a. metadata__settings__description__old b. metadata__settings__description__new This endpoint can be paginated with 'start' and 'limit' parameters 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 ⚠️ _Only available to superusers_ 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 ⚠️ _Only available to superusers_ Export project history logs and send it by email to the requesting user. 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 Invites sent or received by current user about transferring project ownership. List can be filtered with `mode` parameter, e.g.: display only received invites. Possible values for `mode`: - `sender` - `recipient` 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 Where the assets `uid` are given in the payload's list 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/ErrorObject' examples: BadRequest: value: detail: 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 It can be useful to monitor the invite status while the transfer is being processed 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 Update the status of an invite. Status accepted: - `cancelled` - `accepted` - `declined` **Notes**: - _When submitting `accepted` the invite status becomes automatically `in_progress`_ - _Only the sender can cancel an invite, and **if only if** the invite is still pending._ - _Only the recipient can accept or decline, **if and only if** the invite is still pending._ 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/ErrorObject' examples: BadRequest: value: detail: field_name: - Error message summary: Bad request description: '' delete: operationId: api_v2_project_ownership_invites_destroy description: | ## Delete invite 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 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 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 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 * Note: `{obj_type}` can either be `users` or `assets` 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/ErrorObject' examples: BadRequest: value: detail: field_name: - Error message summary: Bad request description: '' post: operationId: api_v2_project_views_export_create description: | ## Create an export for the requested object * Note: `{obj_type}` can either be `users` or `assets` 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/ErrorObject' examples: BadRequest: value: detail: 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 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/ErrorObject' examples: BadRequest: value: detail: 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 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 Returns a paginated list of assets visible within the project view, including only `uid`, `name`, and `deployment_status` (`draft`, `deployed`, or `archived`). Use the `q` query parameter to filter by asset type (e.g. `?q=asset_type:survey`). Responses do not include a `count` field. Use the `next` and `previous` links to paginate through results. 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 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). Authentik can send a PUT request to update a user's details. If it tries to update a user to have a username or email that already exists on another account, 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 ## Track Service Usage Tracks the total usage of different services for the logged-in user.
Tracks the submissions and NLP seconds/characters for the current month/year/all time.
Tracks the current total storage used.
Note: this endpoint is not currently used by the frontend to display usage information.
See `/api/v2/organizations/{organization_id}/service_usage/` for the endpoint we use on the Usage page.
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/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. This will immediately change their subscription to the new plan if upgrading, prorating the charge. If the user is downgrading to a lower price, it will schedule the change at the end of the current billing period. 
        GET /api/v2/stripe/change-plan/?subscription_id={subscription_id}&price_id={price_id}
> Example > > curl -X GET https://[kpi]/api/v2/stripe/change-plan/ > **Payload** > > { > "price_id": "price_A34cds8fmske3tf", > "subscription_id": "sub_s9aNFrd2fsmld4gz", > "quantity": 100000 > } where: * "price_id" (required) is the Stripe Price ID for the plan the user is changing to. * "quantity" is the quantity for the new subscription price (default: 1). * "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/ErrorObject' examples: BadRequest: value: detail: 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 This endpoint is cached for an amount of time determined by ENDPOINT_CACHE_DURATION 
        GET /api/v2/stripe/products/
> Example > > curl -X GET https://[kpi]/api/v2/stripe/products/ > Response > > HTTP 200 Ok > { > "count": ... > "next": ... > "previous": ... > "results": [ > { > "id": string, > "name": string, > "type": string, > "prices": [ > { > "id": string, > "nickname": string, > "currency": string, > "type": string, > "recurring": { > "aggregate_usage": string ('sum', 'last_during_period`, `last_ever`, `max`) > "interval": string ('month', 'year', 'week', 'day') > "interval_count": int, > "usage_type": string ('metered', 'licensed') > }, > "unit_amount": int (cents), > "human_readable_price": string, > "metadata": {}, > "active": bool, > "product": string, > "transform_quantity": null | {'round': 'up'|'down', 'divide_by': int} > }, > ... > ], > "metadata": {}, > }, > ... > ] > } > ### Note: unit_amount is price in cents (assuming currency is USD/AUD/CAD/etc.) ## 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 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/tags/{taguid__uid}/: get: operationId: api_v2_tags_retrieve description: | ## Retrieve a tag's data parameters: - in: path name: taguid__uid schema: type: string required: true tags: - Manage projects and library content security: - BasicAuth: [] - TokenAuth: [] - {} responses: '200': content: application/json: schema: $ref: '#/components/schemas/TagRetrieveResponse' 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/terms-of-service/: get: operationId: api_v2_terms_of_service_list description: | ## List the different terms of service 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 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. Search can be made with `q` parameter to search for the term in names and codes. Results are order by name. 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 * `code` - is the unique identifier of a specific language 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. Search can be made with `q` parameter to search for the term in names and codes. Results are ordered by name. 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/ErrorObject' examples: BadRequest: value: detail: 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 * `code` - is the unique identifier of a specific language 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 ⚠️ _Only available to superusers_ ## Filterable fields by string: Supports partial filtering - username - first_name - last_name - email - user_uid - organization__name - organization__role (e.g., admin, member, owner) - organization__website - extra_details__data__organization_type - `extra_details__data__` (other string fields, e.g., name, sector, country...) ## Filterable fields by int: Supports exact matching and range operators (e.g., gte, lte) **Total NLP Usage** - service_usage__total_nlp_usage__asr_seconds_all_time - service_usage__total_nlp_usage__mt_characters_all_time - service_usage__total_nlp_usage__asr_seconds_current_period - service_usage__total_nlp_usage__mt_characters_current_period **Total Storage/Submissions** - service_usage__total_storage_bytes - service_usage__total_submission_count__cumulative - service_usage__total_submission_count__current_period **Service Usage Balances** Prefix: `service_usage__balances____` Metric: - submission - asr_seconds - mt_characters - storage_bytes Value: - balance_value - balance_percent - effective_limit Ex: `service_usage__balances__submission__balance_value` **Asset Count** - asset_count - active_project_count ## Filterable fields by date: Supports exact matching and range operators (e.g., gte, lte) - date_joined - last_login - last_updated (Represents the last modified timestamp of the materialized view) - extra_details__date_removal_requested - extra_details__date_removed - extra_details_password_date_changed ## Filterable fields by boolean: - is_superuser - is_staff - is_active - validated_email - extra_details__validated_password - mfa_is_active - sso_is_active - accepted_tos - extra_details__data__newsletter_subscription - service_usage__balances__*metric*__exceeded (metric: submission, asr_seconds, mt_characters, storage_bytes) - account_restricted ## Filterable fields by list: Subscription filtering: Has subscriptions `?q=subscriptions__0__id__isnull:False` No subscriptions `?q=subscriptions__0__id__isnull:True` Subscription id `?q=subscriptions[]__id:sub_1QwPItAR39rDI89stzLJ040p` Active subscriptions `?q=subscriptions[]__status:active` 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/ErrorObject' examples: BadRequest: value: detail: field_name: - Error message summary: Bad request description: '' /api/v2/users/: get: operationId: api_v2_users_list description: | ## List users ⚠️ _Only available to superusers_ Search can be made with `q` parameter. Allowed fields are: - `username` - `is_active` - `email` - `date_joined` - `last_login` - `extra_details__data__` 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 ⚠️ _Regular users have access to active users only_ 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 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 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/ErrorObject' examples: BadRequest: value: detail: field_name: - Error message summary: Bad request description: '' delete: operationId: me_destroy description: | ## Delete current user > Payload Example: > > { > "confirm": "user__extra_details__uid", > } ### !! 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. !! 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/ErrorObject' examples: BadRequest: value: detail: field_name: - Error message summary: Bad request description: '' /me/emails/: get: operationId: me_emails_list description: | ## View current user's email 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 The new email will be unverified and replace existing unverified, non-primary emails. New email is not usable until verified. tags: - User / team / organization / usage requestBody: content: application/json: schema: $ref: '#/components/schemas/EmailRequestPayload' 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/ErrorObject' examples: BadRequest: value: detail: field_name: - Error message summary: Bad request description: '' /me/social-accounts/: get: operationId: me_social_accounts_list description: | ## List user's social accounts 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 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 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: '' '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 and behavior of django-allauth, some of which can also impact the frontend. Therefore, relevant configuration options are exposed via this endpoint. The data returned is not user/authentication dependent. Hence, it suffices to only fetch this data once at boot time of your application. 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 and behavior of django-allauth, some of which can also impact the frontend. Therefore, relevant configuration options are exposed via this endpoint. The data returned is not user/authentication dependent. Hence, it suffices to only fetch this data once at boot time of your application. 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. 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. 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. 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. 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. 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. 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 required depends on the configuration of django-allauth. Additionally, if a custom signup form is used there may be other custom properties required. parameters: - $ref: '#/components/parameters/Client' requestBody: $ref: '#/components/requestBodies/Signup' 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': description: | Not authenticated. content: application/json: schema: $ref: '#/components/schemas/AuthenticationResponse' examples: pending_email: $ref: '#/components/examples/UnauthenticatedPendingEmailVerification' '403': description: | Forbidden. For example, when signup is closed. content: application/json: schema: $ref: '#/components/schemas/ForbiddenResponse' '409': description: | Conflict. For example, when signing up while user is logged in. 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 required depends on the configuration of django-allauth. Additionally, if a custom signup form is used there may be other custom properties required. parameters: - $ref: '#/components/parameters/Client' requestBody: $ref: '#/components/requestBodies/Signup' 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': description: | Not authenticated. content: application/json: schema: $ref: '#/components/schemas/AuthenticationResponse' examples: pending_email: $ref: '#/components/examples/UnauthenticatedPendingEmailVerification' '403': description: | Forbidden. For example, when signup is closed. content: application/json: schema: $ref: '#/components/schemas/ForbiddenResponse' '409': description: | Conflict. For example, when signing up while user is logged in. 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 the user by email. parameters: - $ref: '#/components/parameters/EmailVerificationKey' - $ref: '#/components/parameters/Client' responses: '200': $ref: '#/components/responses/EmailVerificationInfo' '400': description: | An input error occurred. 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. 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, email addresses are either verified by opening a link that is sent to their email address, or, by inputting a code that is sent. On the API, both cases are handled identically. Meaning, the required key is either the one from the link, or, the code itself. Note that a status code of 401 does not imply failure. It indicates that the email verification was successful, yet, the user is still not signed in. For example, in case `ACCOUNT_LOGIN_ON_EMAIL_CONFIRMATION` is set to `False`, a 401 is returned when verifying as part of login/signup. 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. 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. 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 the user by email. parameters: - $ref: '#/components/parameters/EmailVerificationKey' - $ref: '#/components/parameters/Client' responses: '200': $ref: '#/components/responses/EmailVerificationInfo' '400': description: | An input error occurred. 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. 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, email addresses are either verified by opening a link that is sent to their email address, or, by inputting a code that is sent. On the API, both cases are handled identically. Meaning, the required key is either the one from the link, or, the code itself. Note that a status code of 401 does not imply failure. It indicates that the email verification was successful, yet, the user is still not signed in. For example, in case `ACCOUNT_LOGIN_ON_EMAIL_CONFIRMATION` is set to `False`, a 401 is returned when verifying as part of login/signup. 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. 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. 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. Requires `ACCOUNT_EMAIL_VERIFICATION_SUPPORTS_RESEND = True`. 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. 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. Requires `ACCOUNT_EMAIL_VERIFICATION_SUPPORTS_RESEND = True`. 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. 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 of 401 does not imply failure. It merely indicates that the phone number verification was successful, yet, the user is still not signed in. 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthenticated' '409': description: | Conflict. The phone verification flow is not pending. 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 of 401 does not imply failure. It merely indicates that the phone number verification was successful, yet, the user is still not signed in. 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': $ref: '#/components/responses/Unauthenticated' '409': description: | Conflict. The phone verification flow is not pending. 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. Requires `ACCOUNT_PHONE_VERIFICATION_SUPPORTS_RESEND = True`. 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. 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. Requires `ACCOUNT_PHONE_VERIFICATION_SUPPORTS_RESEND = True`. 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. 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 recently authenticated. If you try to perform such an action without having been recently authenticated, a `401` status is returned, listing flows that can be performed to reauthenticate. One such flow is the flow with ID `reauthenticate`, which allows for the user to input the password. This is the endpoint related towards that flow. 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 recently authenticated. If you try to perform such an action without having been recently authenticated, a `401` status is returned, listing flows that can be performed to reauthenticate. One such flow is the flow with ID `reauthenticate`, which allows for the user to input the password. This is the endpoint related towards that flow. 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 `ACCOUNT_PASSWORD_RESET_BY_CODE_ENABLED` is `True`, the procedure is either stateless or stateful. In case codes are used, it is stateful, and a new `password_reset_by_code` flow is started. In this case, on a successful password reset request, you will receive a 401 indicating the pending status of this flow. In case password reset is configured to use (stateless) links, you will receive a 200 on a successful password reset request. 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. 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 `ACCOUNT_PASSWORD_RESET_BY_CODE_ENABLED` is `True`, the procedure is either stateless or stateful. In case codes are used, it is stateful, and a new `password_reset_by_code` flow is started. In this case, on a successful password reset request, you will receive a 401 indicating the pending status of this flow. In case password reset is configured to use (stateless) links, you will receive a 200 on a successful password reset request. 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. 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 key passed is either the key encoded in the password reset URL that the user has received per email, or, the password reset code in case of `ACCOUNT_PASSWORD_RESET_BY_CODE_ENABLED`. Note that in case of a code, the number of requests you can make is limited (by `ACCOUNT_PASSWORD_RESET_BY_CODE_MAX_ATTEMPTS`). 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. 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. 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 the new password. After successfully completing the password reset, the user is either logged in (in case `ACCOUNT_LOGIN_ON_PASSWORD_RESET` is `True`), or, the user will need to proceed to the login page. In case of the former, a `200` status code is returned, in case of the latter a 401. 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. 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 key passed is either the key encoded in the password reset URL that the user has received per email, or, the password reset code in case of `ACCOUNT_PASSWORD_RESET_BY_CODE_ENABLED`. Note that in case of a code, the number of requests you can make is limited (by `ACCOUNT_PASSWORD_RESET_BY_CODE_MAX_ATTEMPTS`). 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. 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. 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 the new password. After successfully completing the password reset, the user is either logged in (in case `ACCOUNT_LOGIN_ON_PASSWORD_RESET` is `True`), or, the user will need to proceed to the login page. In case of the former, a `200` status code is returned, in case of the latter a 401. 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. 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 this endpoint results in a user facing redirect (302), this call is only available in a browser, and must be called in a synchronous (non-XHR) manner. 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 by other means. For example, in case of a mobile app, the authentication flow runs completely on the device itself, without any interaction with the API. Then, when the (device) authentication completes and the mobile app receives an access and/or ID token, it can hand over these tokens via this endpoint to authenticate on the server. 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. 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 by other means. For example, in case of a mobile app, the authentication flow runs completely on the device itself, without any interaction with the API. Then, when the (device) authentication completes and the mobile app receives an access and/or ID token, it can hand over these tokens via this endpoint to authenticate on the server. 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. 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 insufficient information received from the provider to automatically complete the signup process, an additional step is needed to complete the missing data before the user is fully signed up and authenticated. The information available so far, such as the pending provider account, can be retrieved via this endpoint. parameters: - $ref: '#/components/parameters/Client' responses: '200': $ref: '#/components/responses/ProviderSignup' '409': description: | Conflict. The provider signup flow is not pending. 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 insufficient information received from the provider to automatically complete the signup process, an additional step is needed to complete the missing data before the user is fully signed up and authenticated. 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. content: application/json: schema: $ref: '#/components/schemas/ForbiddenResponse' '409': description: | Conflict. The provider signup flow is not pending. 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 insufficient information received from the provider to automatically complete the signup process, an additional step is needed to complete the missing data before the user is fully signed up and authenticated. The information available so far, such as the pending provider account, can be retrieved via this endpoint. parameters: - $ref: '#/components/parameters/Client' responses: '200': $ref: '#/components/responses/ProviderSignup' '409': description: | Conflict. The provider signup flow is not pending. 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 insufficient information received from the provider to automatically complete the signup process, an additional step is needed to complete the missing data before the user is fully signed up and authenticated. 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. content: application/json: schema: $ref: '#/components/schemas/ForbiddenResponse' '409': description: | Conflict. The provider signup flow is not pending. 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 flows has ID `mfa_authenticate`, that indicates that the Two-Factor Authentication stage needs to be completed. 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 flows has ID `mfa_authenticate`, that indicates that the Two-Factor Authentication stage needs to be completed. 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 recently authenticated. If you try to perform such an action without having been recently authenticated, a `401` status is returned, listing flows that can be performed to reauthenticate. One such flow is the flow with ID `mfa_reauthenticate`, which allows for the user to input an authenticator code (e.g. TOTP or recovery code). This is the endpoint related towards that flow. 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 recently authenticated. If you try to perform such an action without having been recently authenticated, a `401` status is returned, listing flows that can be performed to reauthenticate. One such flow is the flow with ID `mfa_reauthenticate`, which allows for the user to input an authenticator code (e.g. TOTP or recovery code). This is the endpoint related towards that flow. 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. 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. 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. 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. 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. 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. 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 description: | Disconnect a third-party provider account, returning the remaining accounts that are still connected. The disconnect is not allowed if it would leave the account unusable. For example, if no password was set up yet. 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 description: | Disconnect a third-party provider account, returning the remaining accounts that are still connected. The disconnect is not allowed if it would leave the account unusable. For example, if no password was set up yet. 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. 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 description: | The following functionality is available: - Adding a new email address for an already signed in user (`ACCOUNT_CHANGE_EMAIL = False`). - Change to a new email address for an already signed in user (`ACCOUNT_CHANGE_EMAIL = True`). - Change to a new email address during the email verification process at signup (`ACCOUNT_EMAIL_VERIFICATION_SUPPORTS_CHANGE = True`). In all cases, an email verification mail will be sent containing a link or code that needs to be verified. 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. 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 sending emails is rate limited, so when you send too many requests the email will not be sent. 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. 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 can be marked as primary. 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. 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. 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 description: | The following functionality is available: - Adding a new email address for an already signed in user (`ACCOUNT_CHANGE_EMAIL = False`). - Change to a new email address for an already signed in user (`ACCOUNT_CHANGE_EMAIL = True`). - Change to a new email address during the email verification process at signup (`ACCOUNT_EMAIL_VERIFICATION_SUPPORTS_CHANGE = True`). In all cases, an email verification mail will be sent containing a link or code that needs to be verified. 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. 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 sending emails is rate limited, so when you send too many requests the email will not be sent. 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. 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 can be marked as primary. 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. 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 endpoint returns a list of phone numbers, at most one entry is returned. 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 description: | The following functionality is available: - Initiate the phone number change process for signed in users. - Change to a new phone number during the phone number verification process at signup for unauthenticated users. Note that this requires: `ACCOUNT_PHONE_VERIFICATION_SUPPORTS_CHANGE = True`. In both cases, after posting a new phone number, proceed with the phone verification endpoint to confirm the change of the phone number by posting the verification code. 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. 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 endpoint returns a list of phone numbers, at most one entry is returned. 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 description: | The following functionality is available: - Initiate the phone number change process for signed in users. - Change to a new phone number during the phone number verification process at signup for unauthenticated users. Note that this requires: `ACCOUNT_PHONE_VERIFICATION_SUPPORTS_CHANGE = True`. In both cases, after posting a new phone number, proceed with the phone verification endpoint to confirm the change of the phone number by posting the verification code. 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. 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. 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 application which was generated using the TOTP authenticator secret retrieved from the TOTP authenticator status endpoint. 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 sufficiently recent, a reauthentication flow (`401`) will is presented. 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. 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 application which was generated using the TOTP authenticator secret retrieved from the TOTP authenticator status endpoint. 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 sufficiently recent, a reauthentication flow (`401`) will is presented. 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. 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. 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 description: | Retrieve information about the authentication status for the current session. 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. 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 description: | Retrieve information about the authentication status for the current session. 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. 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 description: | Used to retrieve a new access token. Depending on `settings.HEADLESS_JWT_ROTATE_REFRESH_TOKEN`, a new refresh token is returned as well. 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 password must be provider. However, accounts that were created by signing up using a third-party provider do not have a password set. In that case, the current password is not required. 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 password must be provider. However, accounts that were created by signing up using a third-party provider do not have a password set. In that case, the current password is not required. 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 * `automatic_google_translation` - automatic_google_translation * `manual_transcription` - manual_transcription * `manual_translation` - manual_translation * `manual_qual` - manual_qual * `automatic_bedrock_qual` - automatic_bedrock_qual ActionIdEnum: enum: - automatic_google_transcription - automatic_google_translation type: string description: |- * `automatic_google_transcription` - automatic_google_transcription * `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 format: uri example: https://kf.kobotoolbox.org/api/v2/assets/a3C9wWefqZVkChNLKqqXVZ/ nullable: true 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 format: date-time nullable: true version_id: type: string readOnly: true nullable: true version__content_hash: type: string readOnly: true nullable: true version_count: type: integer readOnly: true has_deployment: type: boolean readOnly: true deployed_version_id: type: string nullable: true 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 kml_legacy: type: string spss_labels: type: string xls_legacy: type: string xls: type: string zip_legacy: type: string required: - csv - csv_legacy - kml_legacy - xls - xls_legacy - zip_legacy readOnly: true deployment__submission_count: type: integer readOnly: true deployment__last_submission_time: type: string format: date-time nullable: true readOnly: true deployment__encrypted: type: boolean readOnly: true deployment__uuid: type: string nullable: true 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' items: type: string nullable: true 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 additionalProperties: {} nullable: true readOnly: true owner_label: type: string readOnly: true last_modified_by: type: string readOnly: true nullable: true created_by: type: string readOnly: true nullable: 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 nullable: true 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 * `deployed` - Deployed * `draft` - Draft * `-` - - 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. Used 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 * `empty` - empty * `question` - question * `block` - block * `survey` - survey * `template` - template * `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 AuthLevelEnum: enum: - no_auth - basic_auth type: string description: |- * `no_auth` - no_auth * `basic_auth` - basic_auth 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 nullable: true 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. * `good` - Good * `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. * `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: allOf: - $ref: '#/components/schemas/BulkActionUserResponse' nullable: true 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 nullable: true previous: type: string nullable: true 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: allOf: - $ref: '#/components/schemas/BulkActionUserResponse' nullable: true 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 * `in_progress` - in_progress * `complete` - complete * `cancelled` - cancelled BulkActionSubmissionStatusResponse: type: object properties: uuid: type: string status: $ref: '#/components/schemas/BulkActionSubmissionStatusResponseStatusEnum' error: type: string nullable: true required: - error - status - uuid BulkActionSubmissionStatusResponseStatusEnum: enum: - pending - in_progress - complete - cancelled - failed type: string description: |- * `pending` - pending * `in_progress` - in_progress * `complete` - complete * `cancelled` - cancelled * `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 * `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 * `deployed` - deployed * `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 _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 nullable: true 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 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 EmailRequestPayload: type: object properties: email: type: string format: email 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: terms_of_service_url: type: string nullable: true privacy_policy_url: type: string nullable: true source_code_url: type: string nullable: true support_email: type: string nullable: true support_url: type: string nullable: true academy_url: type: string nullable: true community_url: type: string nullable: true 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 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 nullable: true 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 - 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 - 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 ErrorObject: type: object properties: detail: {} required: - detail 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.orguser/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 * `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 nullable: true 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 readOnly: true nullable: 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 * `1` - pending * `3` - processing * `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 format: uri url: type: string format: uri name: type: string assetUid: type: string required: - assetUid - destination - url 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 * `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 * `cancelled` - Cancelled * `declined` - Declined * `expired` - Expired * `pending` - Pending * `resent` - Resent InviteeRoleEnum: enum: - admin - member type: string description: |- * `admin` - admin * `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 format: date-time nullable: true 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: $ref: '#/components/schemas/MemberRoleEnum' url: type: string format: uri example: https://kf.kobotoolbox.org/api/v2/organizations/orgR6zUBwMHop2mgGygtFd6c/members/bob/ user: type: string format: uri example: https://kf.kobotoolbox.org/api/v2/users/bob/ user__username: type: string user__email: type: string format: email user__extra_details__name: type: string user__has_mfa_enabled: type: boolean date_joined: type: string format: date-time user__is_active: type: boolean invite: allOf: - $ref: '#/components/schemas/InviteResponse' nullable: true required: - date_joined - invite - role - url - user - user__email - user__extra_details__name - user__has_mfa_enabled - user__is_active - user__username MemberRoleEnum: enum: - admin - member - owner type: string description: |- * `admin` - admin * `member` - member * `owner` - owner MetadataField: type: object properties: name: type: string label: type: string type: type: string required: type: boolean options: type: array items: $ref: '#/components/schemas/MetadataFieldOption' nullable: true 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. Possible keys: "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 add-on. readOnly: true limits_remaining: description: The amount of each of the add-on's individual limits left to use. organization: type: string nullable: true product: type: string nullable: true 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 * `government` - Government institution * `educational` - Educational organization * `commercial` - A commercial/for-profit company * `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 format: date-time nullable: true 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 endpoint 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 nullable: true 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 readOnly: true nullable: 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. * `one_time` - One-time * `recurring` - Recurring recurring: allOf: - $ref: '#/components/schemas/Recurring' nullable: true unit_amount: type: integer maximum: 9223372036854775807 minimum: -9223372036854775808 format: int64 nullable: true 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: nullable: true 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: nullable: true 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. * `one_time` - One-time * `recurring` - Recurring recurring: allOf: - $ref: '#/components/schemas/Recurring' nullable: true unit_amount: type: integer maximum: 9223372036854775807 minimum: -9223372036854775808 format: int64 nullable: true 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: nullable: true 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: nullable: true 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 nullable: true 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. * `good` - Good * `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 * `create_prorations` - Create prorations * `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 nullable: true 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 nullable: true required: - client_id - name - provider - provider_id StripeIntervalEnum: enum: - day - week - month - year type: string description: |- * `day` - Day * `week` - Week * `month` - Month * `year` - Year StripePriceType: enum: - one_time - recurring type: string description: |- * `one_time` - One-time * `recurring` - Recurring StripeProductType: enum: - good - service type: string description: |- * `good` - Good * `service` - Service StripeUsageType: enum: - metered - licensed type: string description: |- * `metered` - Metered * `licensed` - Licensed Subscription: type: object properties: items: type: array items: $ref: '#/components/schemas/SubscriptionItem' schedule: $ref: '#/components/schemas/SubscriptionSchedule' application_fee_percent: type: string format: decimal pattern: ^-?\d{0,3}(?:\.\d{0,2})?$ nullable: true 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 nullable: true 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 format: date-time nullable: true description: The datetime this object was created in stripe. metadata: nullable: true 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 nullable: true description: A description of this object. billing_cycle_anchor: type: string format: date-time nullable: true 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: nullable: true description: Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. cancel_at: type: string format: date-time nullable: true 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 format: date-time nullable: true 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. * `charge_automatically` - Charge automatically * `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 maximum: 2147483647 minimum: -2147483648 nullable: true 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: nullable: true 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 format: date-time nullable: true 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 format: date-time nullable: true 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: nullable: true description: If specified, payment collection for this subscription will be paused. pending_invoice_item_interval: nullable: true 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: nullable: true 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 * `always_invoice` - Always invoice * `create_prorations` - Create prorations * `none` - None oneOf: - $ref: '#/components/schemas/ProrationBehaviorEnum' - $ref: '#/components/schemas/BlankEnum' proration_date: type: string format: date-time nullable: true 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 maximum: 2147483647 minimum: -2147483648 nullable: true description: The quantity applied to this subscription. This value will be `null` for multi-plan subscriptions start_date: type: string format: date-time nullable: true 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. * `active` - Active * `canceled` - Canceled * `incomplete` - Incomplete * `incomplete_expired` - Incomplete Expired * `past_due` - Past due * `trialing` - Trialing * `unpaid` - Unpaid trial_end: type: string format: date-time nullable: true description: If the subscription has a trial, the end of that trial. trial_start: type: string format: date-time nullable: true description: If the subscription has a trial, the beginning of that trial. djstripe_owner_account: type: string nullable: true description: The Stripe Account this object belongs to. customer: type: string description: The customer associated with this subscription. default_payment_method: type: string nullable: true 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 nullable: true 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 nullable: true description: The most recent invoice this subscription has generated. pending_setup_intent: type: string nullable: true 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 title: ID nullable: true 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 maximum: 2147483647 minimum: 0 nullable: true 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`. * `active` - Active * `canceled` - Canceled * `completed` - Completed * `not_started` - Not started * `released` - Released required: - phases - status SubscriptionScheduleStatusEnum: enum: - active - canceled - completed - not_started - released type: string description: |- * `active` - Active * `canceled` - Canceled * `completed` - Completed * `not_started` - Not started * `released` - Released SubscriptionStatusEnum: enum: - active - canceled - incomplete - incomplete_expired - past_due - trialing - unpaid type: string description: |- * `active` - Active * `canceled` - Canceled * `incomplete` - Incomplete * `incomplete_expired` - Incomplete Expired * `past_due` - Past due * `trialing` - Trialing * `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 - _dependency - _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 - _dependency - _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 url: type: string format: uri example: https://kf.kobotoolbox.org/api/v2/tags/tg3c5giitsQUMCJNNoDEpQ/ required: - name - url TagRetrieveResponse: type: object properties: name: type: string url: type: string format: uri example: https://kf.kobotoolbox.org/api/v2/tags/tg3c5giitsQUMCJNNoDEpQ/ assets: type: array items: type: string format: uri example: https://kf.kobotoolbox.org/api/v2/assets/a5owyo85mHyFazzgsZK45c/ parent: type: string format: uri example: https://kf.kobotoolbox.org/api/v2/tags/ uid: type: string required: - assets - name - parent - uid - url 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 required: - content_hash - date_deployed - date_modified - uid - url 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 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 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. 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. 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. type: array items: type: integer example: 123 required: - sessions PhoneNumber: type: object description: | A phone number. 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. 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. 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). example: ufwcig0zen9skyd545jc0fkq813ghar2 access_token: type: string description: | The access token (`app` clients only). example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdW AuthenticationMeta: allOf: - $ref: '#/components/schemas/BaseAuthenticationMeta' - type: object description: | Metadata available in an authentication related response. 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. 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. 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. items: $ref: '#/components/schemas/AuthenticationMethod' required: - flows - user - methods type: object AuthenticationMethod: oneOf: - type: object title: | Authenticated by username/email login 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 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. 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. 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 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 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 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) example: 123.apps.googleusercontent.com ProviderToken: type: object properties: provider: $ref: '#/components/schemas/ProviderID' process: $ref: '#/components/schemas/Process' token: description: | The token. type: object properties: client_id: $ref: '#/components/schemas/ClientID' id_token: type: string description: | The ID token. example: eyJhbGciOiJI access_token: type: string description: | The access token. 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. Note that this is not to be mistaken with the callback URL that you configure over at the OAuth provider during the OAuth app/client setup. The flow is as follows: 1. Your frontend redirects to the headless provider redirect endpoint in a synchronous (non-XHR) manner, informing allauth (by means of `callback_url`) where to redirect to after the provider handshake is completed. 2. Headless will redirect to the (OAuth) identity provider to initiate the handshake, passing along a different callback URL to the provider: one that points to an allauth backend URL. This is the URL that you need to have setup at your OAuth app/client configuration. Note that this must be a backend URL as providers can use POST requests to perform their callbacks, which is something a frontend would not be able to handle. 3. After the authorization at the provider is completed, the provider redirects to the *backend* allauth callback URL, which will then redirect back to the *frontend* callback URL. 4. Your frontend is now expected to fetch the current session to determine what the next course of action is. The user could be authenticated at this point, or another flow is pending (e.g. email verification, or, provider signup). In case of errors a `?error=` is passed to the frontend callback URL. 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. example: wizard Email: type: string description: | The email address. example: email@domain.org Phone: type: string description: | The phone number. example: '+314159265359' AccessToken: type: string description: | The access token. example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdW RefreshToken: type: string description: | The refresh token. 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. example: 123 SocialAccountConfiguration: type: object description: | Configuration of the Django `allauth.socialaccount` app. properties: providers: $ref: '#/components/schemas/ProviderList' required: - providers MFAConfiguration: type: object description: | Configuration of the Django `allauth.mfa` app. properties: supported_types: type: array description: | Matches `settings.MFA_SUPPORTED_TYPES`. items: $ref: '#/components/schemas/AuthenticatorType' required: - supported_types UserSessionsConfiguration: type: object description: | Configuration of the Django `allauth.usersessions` app. properties: track_activity: type: boolean description: | Matches `settings.USERSESSIONS_TRACK_ACTIVITY`. 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`) example: 1711555057.065702 AuthenticatorCode: type: string description: | An authenticator code. example: '314159' Code: type: string description: | An one-time code. example: NQ3TM5 AuthenticatorType: type: string enum: - recovery_codes - totp - webauthn description: | The type of authenticator. Password: type: string description: | The password. 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. param: type: string example: email description: | The name of the input parameter that was incorrect. message: type: string example: Enter a valid email address. description: | A human readable error message. required: - code - message Process: type: string description: | The process to be executed when the user successfully authenticates. When set to `login`, the user will be logged into the account to which the provider account is connected, or if no such account exists, a signup will occur. If set to `connect`, the provider account will be connected to the list of provider accounts for the currently authenticated user. enum: - login - connect example: login ProviderID: type: string description: | The provider ID. example: google ProviderAccountID: type: string description: | The provider specific account ID. 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. required: - type - id - name RecoveryCodesAuthenticator: allOf: - $ref: '#/components/schemas/BaseAuthenticator' - type: object properties: type: type: string description: | The authenticator type. enum: - recovery_codes total_code_count: type: integer description: | The total number of recovery codes that initially were available. example: 10 unused_code_count: type: integer description: | The number of recovery codes that are unused. 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. 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. name: type: string description: | The name of the provider. example: Google client_id: type: string description: | The client ID (in case of OAuth2 or OpenID Connect based providers) 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) example: https://accounts.google.com/.well-known/openid-configuration flows: type: array description: | The authentication flows the provider integration supports. 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. 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. 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. 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. 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. value: status: 400 errors: - message: | You cannot deactivate two-factor authentication. code: cannot_generate_recovery_codes 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. value: status: 400 errors: - message: Incorrect code. code: incorrect_code param: code InvalidEmailVerificationKey: summary: | Email verification key invalid. 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. value: status: 400 errors: - message: The password reset token was invalid. code: token_invalid param: key InvalidProviderToken: summary: | Provider token invalid. 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 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 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 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 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 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 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. 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. 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. example: email@domain.org primary: type: boolean enum: - true description: | Primary flag. 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. 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`. 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), but may enforce additional multi-factor authentication (MFA) requirements. Omit the parameter to disable. responses: AddAuthenticatorConflict: description: | The account prohibits adding an authenticator, e.g. because of an unverified email address. 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. 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. content: application/json: schema: $ref: '#/components/schemas/AuthenticatedResponse' examples: authenticated: $ref: '#/components/examples/AuthenticatedByPassword' AuthenticatedByCode: description: | Authenticated by code. content: application/json: schema: $ref: '#/components/schemas/AuthenticatedResponse' examples: authenticated: $ref: '#/components/examples/AuthenticatedByCode' AuthenticatedByPasswordAnd2FA: description: | Authenticated by password and 2FA. 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. content: application/json: schema: oneOf: - $ref: '#/components/schemas/AuthenticationResponse' - $ref: '#/components/schemas/ReauthenticationResponse' Configuration: description: | The django-allauth configuration. content: application/json: schema: $ref: '#/components/schemas/ConfigurationResponse' EmailAddresses: description: | List of email addresses. 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. content: application/json: schema: $ref: '#/components/schemas/ForbiddenResponse' NotFound: description: | Not found. 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. content: application/json: schema: $ref: '#/components/schemas/PhoneNumbersResponse' ProviderAccounts: description: | List of third-party provider accounts. 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. 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. content: application/json: schema: $ref: '#/components/schemas/ReauthenticationResponse' examples: reauthentication_required: summary: | Reauthentication required 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. 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. 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. content: application/json: schema: $ref: '#/components/schemas/SessionGoneResponse' examples: unauth: $ref: '#/components/examples/UnauthenticatedInitial' StatusOK: description: | A success response. content: application/json: schema: type: object properties: status: $ref: '#/components/schemas/StatusOK' required: - status TooManyRequests: description: | Too many requests. content: application/json: schema: type: object properties: status: type: integer enum: - 429 required: - status TOTPAuthenticator: description: | Information on the TOTP authenticator. 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. 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. example: J4ZKKXTK7NOVU7EPUVY23LCDV4T2QZYM totp_url: type: string description: | otpauth URI from which a QR code can be generated and scanned by OTP clients. 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. 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. 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