KoboToolbox

https://support.kobotoolbox.org/
Admin
KoboToolbox is a suite of tools for humanitarian and development workers to collect, manage, and...
Tokens:82,956
Snippets:1,320
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### v1 Metadata Response Example

Source: https://support.kobotoolbox.org/migrating_api.html

This is an example of the response structure for the v1 metadata endpoint.

```json
{
  "id": 271,
  "xform": 374,
  "data_value": "goose.jpg",
  "data_type": "media",
  "data_file": "/project_owner/form-media/b44a7c2cd0f244e6b405821582364657/goose.jpg",
  "data_file_type": "image/jpeg",
  "file_hash": "md5:93fb96bced1e3b392abfc22934afe51a",
  "url": "https://kc.kobotoolbox.org/api/v1/metadata/271?format=json",
  "from_kpi": true,
  "data_filename": "goose.jpg"
}

```

--------------------------------

### v2 Metadata Response Example

Source: https://support.kobotoolbox.org/migrating_api.html

This is an example of the equivalent response structure for the v2 metadata endpoint, showing changes in field names and structure.

```json
{
  "uid": "afoeCcF3AcGNpWUoM6bvKj9",
  "asset": "http://kf.kobo.localhost/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/",
  "file_type": "form_media",
  "content": "http://kf.kobo.localhost/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/files/afoeCcF3AcGNpWUoM6bvKj9/content/",
  "metadata": {
    "hash": "md5:93fb96bced1e3b392abfc22934afe51a",
    "filename": "goose.jpg",
    "mimetype": "image/jpeg"
  },
  ...
}

```

--------------------------------

### v1 Submission Data Response Example

Source: https://support.kobotoolbox.org/migrating_api.html

Example of a v1 API response for retrieving submission data for a project.

```json
[
  {
    "_id": 49542,
    ...
  }
]

```

--------------------------------

### Instance Name Calculation Example

Source: https://support.kobotoolbox.org/form_settings_xls.html

This example shows how to create a unique instance name using a combination of user-provided fields and the current date. This is useful for generating custom participant or submission IDs.

```xlsform
concat(${lname}, ‘-’, ${fname}, ‘-’, today())
```

--------------------------------

### v2 Submission Data Response Example

Source: https://support.kobotoolbox.org/migrating_api.html

Example of a v2 API response for submission data, highlighting the introduction of pagination with 'count', 'next', and 'previous' fields.

```json
{
  "count": 1200,
  "next": null,
  "previous": null,
  "results": [
    {
      "_id": 49542,
      ...
    }
  ]
}

```

--------------------------------

### v1 Project List Response Example

Source: https://support.kobotoolbox.org/migrating_api.html

Illustrates the structure of a v1 API response for listing projects.

```json
{
  "id": 474,
  "id_string": "a4etXeWtqcoodSxLV8a6Uq",
  "title": "Pathways Initiative",
  "description": "Pathways Initiative",
  "url": "https://kc.kobotoolbox.org/api/v1/data/474.json"
}

```

--------------------------------

### XLSForm Settings Worksheet Example

Source: https://support.kobotoolbox.org/form_settings_xls.html

This example demonstrates the structure of the 'settings' worksheet in XLSForm. It includes common settings like form title, version, default language, and style.

```xlsform
form_title | version | default_language | style  
---|---|---|---
Form settings in XLSForm | v3 | English (en) | pages  
surveychoicessettings
```

--------------------------------

### v2 Form Endpoint Response Example

Source: https://support.kobotoolbox.org/migrating_api.html

This is an example of the JSON response structure for a form retrieved via the v2 API endpoint, showing equivalent fields to the v1 response.

```json
{
  "url": "https://kf.kobotoolbox.org/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/",
  "owner__username": "project_owner",
  "files": [],
  "summary": {
    "geo": false
  },
  "version__content_hash": "05be1113c6ae66665059fea5943ce90a97d966db",
  "deployment__active": true,
  "deployment__submission_count": 1200,
  "deployment__last_submission_time": "2025-06-03T15:16:20.838131Z",
  "deployment__encrypted": false,
  "deployment__uuid": "f739945244514a6bb304dc35d6049880",
  "tag_string": "my_tag,my_other_tag",
  "uid": "a4etXeWtqcoodSxLV8a6Uq",
  "name": "Pathways Initiative",
  "permissions": [
    {
      "url": "https://kf.kobotoolbox.org/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/permission-assignments/pQnggGHaPGGmJtPCbCCVpU/",
      "user": "https://kf.kobotoolbox.org/api/v2/users/project_owner/",
      "permission": "https://kf.kobotoolbox.org/api/v2/permissions/add_submissions/",
      "label": "Add submissions"
    },
    {
      "url": "https://kf.kobotoolbox.org/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/permission-assignments/pcn2g8ezroevNsP7CuCkrf/",
      "user": "https://kf.kobotoolbox.org/api/v2/users/project_owner/",
      "permission": "https://kf.kobotoolbox.org/api/v2/permissions/change_asset/",
      "label": "Edit form"
    },
    {
      "url": "https://kf.kobotoolbox.org/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/permission-assignments/pVMKQ4bDSn5SCAgefzMRLX/",
      "user": "https://kf.kobotoolbox.org/api/v2/users/project_owner/",
      "permission": "https://kf.kobotoolbox.org/api/v2/permissions/change_submissions/",
      "label": "Edit submissions"
    },
    {
      "url": "https://kf.kobotoolbox.org/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/permission-assignments/pwoCoBBLmyWsdF2dXPBaHt/",
      "user": "https://kf.kobotoolbox.org/api/v2/users/project_owner/",
      "permission": "https://kf.kobotoolbox.org/api/v2/permissions/delete_submissions/",
      "label": "Delete submissions"
    },
    {
      "url": "https://kf.kobotoolbox.org/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/permission-assignments/pqDGr7M7au4NsFiuKkEeTr/",
      "user": "https://kf.kobotoolbox.org/api/v2/users/project_owner/",
      "permission": "https://kf.kobotoolbox.org/api/v2/permissions/manage_asset/"
    }
  ]
}
```

--------------------------------

### Example Public Key String

Source: https://support.kobotoolbox.org/encrypting_forms.html?highlight=encryption

This is an example of the public key string format. You will need to copy this entire string, without any extra spaces or line breaks, and paste it into the 'public_key' field in your XLS form settings.

```text
e.g.:Tjhfur1K9+BRQ2USezIPbtyahbfuNqviI5Suhm8maA3JoELRHj9psjf/oNWoG87aFtKNbLrRaCEDP oFMDC9NEzWlv5L49BygeieMu/wg/rtMT0M0kgDbKxw5weJJgyb9P41aMsrqAAAAB3NzaC1yc2EAAAADAQAB AAABAQDfNoFX7bh3bfdW6lGfDht1Ea8PUBLKYjugbHN5jS7j5fHV6dexM+kzvITVgoyjhhKPXeCbaT62vD/ saTqJFXJzlysnZ24fqxNkjreO5K5EQ9c3ggwqML06+AKrFUSP5jpnyJJH8btNwKl6D5pG4ZseHwDUKzZtae xtPTNQz67kdYIKdtCkCsQHVsy4xvy/A0jzfK3xyOkG6j+L
```

--------------------------------

### XLSForm Skip Logic Example

Source: https://support.kobotoolbox.org/skip_logic.html

This is an example of how to manually enter skip logic in XLSForm code. It shows how to reference a question's name using `${question_name}` to set a condition for displaying another question.

```XLSForm
`${Q1} = ‘yes’`
```

--------------------------------

### v1 Form Endpoint Response Example

Source: https://support.kobotoolbox.org/migrating_api.html

This is an example of the JSON response structure for a form retrieved via the v1 API endpoint.

```json
{
  "url": "https://kf.kobotoolbox.org/api/v1/forms/474",
  "formid": 474,
  "metadata": [],
  "owner": "project_owner",
  "public": false,
  "public_data": false,
  "require_auth": true,
  "tags": ["my_tag", "my_other_tag"],
  "title": "Pathways Initiative",
  "users": [
    {
      "user": "project_owner",
      "permissions": [
        "add_xform",
        "change_xform",
        "delete_data_xform",
        "delete_xform",
        "move_xform",
        "report_xform",
        "transfer_xform",
        "validate_xform",
        "view_xform"
      ]
    }
  ],
  "hash": "md5:65ee54b6412379b0e35b27a97d606c29",
  "downloadable": true,
  "encrypted": false,
  "id_string": "a4etXeWtqcoodSxLV8a6Uq",
  "last_submission_time": "2025-06-03T15:16:20.838131Z",
  "uuid": "f739945244514a6bb304dc35d6049880",
  "instances_with_geopoints": false,
  "num_of_submissions": 1200,
  "attachment_storage_bytes": 27240767883
}
```

--------------------------------

### v2 Project List Response Example

Source: https://support.kobotoolbox.org/migrating_api.html

Shows the equivalent v2 API response structure for project data, noting the use of 'uid' instead of sequential integers.

```json
{
  "url": "https://kf.kobotoolbox.org/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/",
  "uid": "a4etXeWtqcoodSxLV8a6Uq",
  "name": "Pathways Initiative",
  "settings": {
    "description": "A humanitarian project supporting access"
  },
  "data": "https://kf.kobotoolbox.org/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/data/"
  ...
}

```

--------------------------------

### XLSForm Survey Worksheet Example with Required Logic

Source: https://support.kobotoolbox.org/required_logic_xls.html

This example demonstrates how to set a question as required based on a select_one reference question. The 'email' question is mandatory only if the 'recontact' question is answered with 'yes'.

```XLSForm
type | name | label | required
select_one yn | recontact | Do you agree to being contacted again for another study in the future? |
text | email | What is your email address? | ${recontact} = ‘yes’
```

--------------------------------

### XLSForm survey worksheet example

Source: https://support.kobotoolbox.org/pull_data_kobotoolbox.html

This example demonstrates how to set up a survey worksheet in XLSForm to use the pulldata() function. It shows how to retrieve 'status' and 'age' from 'eligibility.csv' based on a 'respondent_id'.

```XLSForm
type | name | label | calculation
text | respondent_id | Respondent ID |
calculate | eligibility_status |  | pulldata(‘eligibility’, ‘status’, ‘ID’, ${respondent_id})
note | eligibility_note | Respondent is ${eligibility_status} for the study. |
integer | respondent_age | Respondent age | pulldata(‘eligibility’, ‘age’, ‘ID’, ${respondent_id})
```

--------------------------------

### Define a Range Constraint with AND

Source: https://support.kobotoolbox.org/constraints_xls.html

This example uses the `and` operator to define a valid weight range between 30 and 200 kg (inclusive).

```XLSForm
type | name | label | hint | constraint
integer | weight | How much do you weigh? | Must be between 30 and 200 kg | . >= 30 and . <= 200
```

--------------------------------

### Static Choice Filter Example in XLSForm

Source: https://support.kobotoolbox.org/choice_filters_xls.html

This example demonstrates how to apply a static choice filter to a 'select_one' question. The 'outdoors_activities' question filters the 'activities' list to show only choices marked with 'outdoors' in the 'filter' column of the choices worksheet.

```XLSForm
type | name | label | choice_filter
select_one activities | activities | What activities do you enjoy doing in your free time? |
select_one activities | outdoors_activities | Which of these outdoor activities are available in your city? | filter = ‘outdoors’
```

```XLSForm
list_name | name | label | filter
activities | reading | Reading |
activities | swimming | Swimming | outdoors
activities | running | Running | outdoors
activities | television | Watching television |
activities | hiking | Hiking | outdoors
```

--------------------------------

### Combine Multiple Constraint Conditions with AND

Source: https://support.kobotoolbox.org/constraints_xls.html

Use the `and` operator to ensure all conditions are met. This example restricts age to be between 18 and 65 (exclusive of 65).

```XLSForm
type | name | label | constraint
integer | age | What is your age? | . > 18 and . < 65
```

--------------------------------

### Add a Constraint Referencing Another Question

Source: https://support.kobotoolbox.org/constraints_xls.html

Constraints can reference other questions using the ${question_name} syntax. This example ensures the number of income earners does not exceed the total household size.

```XLSForm
type | name | label | constraint
integer | income | Out of those, how many earn income? | . <= ${household}
```

--------------------------------

### Conditional Variable Based on Regex Match

Source: https://support.kobotoolbox.org/calculations_xls.html

Creates a binary variable ('yes' or 'no') based on whether a respondent's ID matches a specific regular expression pattern. This example checks if the ID starts with 'ML-'.

```XLSForm
if(regex(${id}, '^ML-'), 'yes', 'no')
```

--------------------------------

### Extract Substring from String

Source: https://support.kobotoolbox.org/calculations_xls.html

Extracts a portion of a string, starting from the specified position (1-based index) and for a given length. Adjust the start index and length as needed.

```XLSForm
substr(${question}, 1, 2)
```

--------------------------------

### Add Regular and Guidance Hints in XLSForm

Source: https://support.kobotoolbox.org/question_options_xls.html

Use the 'hint' column for regular hints visible below the question label, and 'guidance_hint' for additional information not displayed by default. Ensure column names are exact.

```XLSForm
type | name | label | hint | guidance_hint
integer | height | What is your height? | In centimeters | If the respondent does not know their height, enter 0
```

--------------------------------

### Configure Map Appearance in Survey Worksheet

Source: https://support.kobotoolbox.org/select_from_map_xls.html

Add 'map' or 'quick map' to the appearance column for select_one or select_one_from_file questions to enable map-based selection. 'map' allows viewing details before selection, while 'quick map' selects the first feature automatically.

```XLSForm
type | name | label | appearance
select_one | location | Where are you currently based? | map
```

--------------------------------

### Define start and end time metadata in XLSForm

Source: https://support.kobotoolbox.org/metadata_xls.html

Use 'start' and 'end' types in the survey worksheet to automatically record when a form submission begins and is finalized. These fields are hidden from respondents and cannot be edited.

```XLSForm
type | name | label
start | start_time |
end | end_time |
```

--------------------------------

### Extract RSA Public Key

Source: https://support.kobotoolbox.org/encrypting_forms.html?highlight=encryption

After generating the private key, use this command to extract the corresponding public key. This public key will be used in your KoboToolbox form settings.

```bash
openssl rsa -in MyPrivateKey.pem -inform PEM -out MyPublicKey.pem -outform PEM -pubout
```

--------------------------------

### Migrating from KPI v1 to KPI v2

Source: https://support.kobotoolbox.org/migrating_api.html

General migration from KPI v1 to v2 involves updating the base path. The exports endpoint is an exception.

```APIDOC
## Migrating from KPI v1 to KPI v2

### Description

Most KPI v1 endpoints can be migrated to v2 by changing the base path from `/endpoint/` to `/api/v2/endpoint/`. The `/exports/` endpoint is an exception and requires a different approach in v2.

### Method

N/A (Conceptual migration guide)

### Endpoint

- **v1:** `/endpoint/`
- **v2:** `/api/v2/endpoint/`

### Exception for exports endpoint

- **v1:** `/exports/` (returns all exports for the authenticated user)
- **v2:** `/api/v2/assets/{asset_uid}/exports/` (scoped per project)
```

--------------------------------

### Basic Select One from File Configuration

Source: https://support.kobotoolbox.org/select_from_file_xls.html

Use `select_one_from_file` in the `type` column, followed by a space and the external file name (e.g., `households.csv`) in the same cell. This links the question to the external choice list.

```XLSForm
type | name | label
select_one_from_file households.csv | hh | Select household
```

--------------------------------

### XLSForm Survey Worksheet Example: Require Email if Phone is Blank

Source: https://support.kobotoolbox.org/required_logic_xls.html

This example shows how to make the 'email' question required only if the 'phone' question was left unanswered. It utilizes the condition `${phone} = ''` to check for a blank response.

```XLSForm
type | name | label | required
note | contact | Please provide your phone number or email address below. |
text | phone | Phone number |
text | email | Email address | ${phone} = ‘’
```

--------------------------------

### Markdown for Headers

Source: https://support.kobotoolbox.org/form_style_xls.html

Use hash symbols to create headers of different sizes, from Header 1 (biggest) to Header 6 (smallest).

```markdown
# Header 1
```

```markdown
###### Header 6
```

--------------------------------

### Creating Headers in Note Questions

Source: https://support.kobotoolbox.org/note_questions.html

Use Markdown to create headers of different sizes for structuring content within note questions. The number of '#' symbols determines the header level.

```markdown
# Header 1 (biggest) to ###### Header 6 (smallest)
```

--------------------------------

### Constraint for Text Questions

Source: https://support.kobotoolbox.org/constraints_xls.html

Text constraints are rarely used but can be applied. This example prevents the input 'Not applicable'.

```XLSForm
type | name | label | constraint
text | other_specify | Other specify | . != 'Not applicable'
```

--------------------------------

### Retrieve API Token using curl

Source: https://support.kobotoolbox.org/api.html

Use this curl command in the terminal to retrieve your API token. Replace `[server-url]` with your KoboToolbox server URL and provide your username and password.

```bash
curl -u username:password "https:/[server-url]/token/?format=json"
```

--------------------------------

### Form Endpoints Migration

Source: https://support.kobotoolbox.org/migrating_api.html

This section details the mapping between v1 and v2 form endpoints and provides examples of their request and response structures.

```APIDOC
## Form Endpoints

These endpoints return detailed attributes of all forms shared with you or about a specific form, where `{uid}` is the unique identifier of the project.

### Endpoint Mapping

`v1` Endpoint | `v2` Equivalent
---|---
`/api/v1/forms` | `/api/v2/assets/?asset_type=survey`
`/api/v1/forms/<pk>` | `/api/v2/assets/{asset_uid}/`

**Note:** The `v2` endpoint follows the same structure for each item as listed below, but introduces pagination. Some properties from the `v1` endpoint are not directly available on the `v2` asset endpoint, but they can still be accessed differently (see the legend below the table for more details).

### Field Mapping

`v1` Field | `v2` Equivalent
---|---
`formid` | `uid`
`owner` | `owner__username`
`metadata` | `files`
`tags` | `tag_string`
`title` | `name`
`public` | _N/A_
`public_data` | _N/A_
`require_auth` | _N/A_
`users` | `permissions`
`hash` | `version__content_hash`
`downloadable` | `deployment__active`
`encrypted` | `deployment__encrypted`
`last_submission_time` | `deployment__last_submission_time`
`uuid` | `deployment__uuid`
`instances_with_geopoints` | `summary.geo`
`num_of_submissions` | `deployment__submission_count`
`attachment_storage_bytes` | _N/A_

### Example v1 Response

```json
{
  "url": "https://kf.kobotoolbox.org/api/v1/forms/474",
  "formid": 474,
  "metadata": [],
  "owner": "project_owner",
  "public": false,
  "public_data": false,
  "require_auth": true,
  "tags": ["my_tag", "my_other_tag"],
  "title": "Pathways Initiative",
  "users": [
    {
      "user": "project_owner",
      "permissions": [
        "add_xform",
        "change_xform",
        "delete_data_xform",
        "delete_xform",
        "move_xform",
        "report_xform",
        "transfer_xform",
        "validate_xform",
        "view_xform"
      ]
    }
  ],
  "hash": "md5:65ee54b6412379b0e35b27a97d606c29",
  "downloadable": true,
  "encrypted": false,
  "id_string": "a4etXeWtqcoodSxLV8a6Uq",
  "last_submission_time": "2025-06-03T15:16:20.838131Z",
  "uuid": "f739945244514a6bb304dc35d6049880",
  "instances_with_geopoints": false,
  "num_of_submissions": 1200,
  "attachment_storage_bytes": 27240767883
}
```

### Equivalent v2 Response

```json
{
  "url": "https://kf.kobotoolbox.org/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/",
  "owner__username": "project_owner",
  "files": [],
  "summary": {
    "geo": false
  },
  "version__content_hash": "05be1113c6ae66665059fea5943ce90a97d966db",
  "deployment__active": true,
  "deployment__submission_count": 1200,
  "deployment__last_submission_time": "2025-06-03T15:16:20.838131Z",
  "deployment__encrypted": false,
  "deployment__uuid": "f739945244514a6bb304dc35d6049880",
  "tag_string": "my_tag,my_other_tag",
  "uid": "a4etXeWtqcoodSxLV8a6Uq",
  "name": "Pathways Initiative",
  "permissions": [
    {
      "url": "https://kf.kobotoolbox.org/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/permission-assignments/pQnggGHaPGGmJtPCbCCVpU/",
      "user": "https://kf.kobotoolbox.org/api/v2/users/project_owner/",
      "permission": "https://kf.kobotoolbox.org/api/v2/permissions/add_submissions/",
      "label": "Add submissions"
    },
    {
      "url": "https://kf.kobotoolbox.org/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/permission-assignments/pcn2g8ezroevNsP7CuCkrf/",
      "user": "https://kf.kobotoolbox.org/api/v2/users/project_owner/",
      "permission": "https://kf.kobotoolbox.org/api/v2/permissions/change_asset/",
      "label": "Edit form"
    },
    {
      "url": "https://kf.kobotoolbox.org/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/permission-assignments/pVMKQ4bDSn5SCAgefzMRLX/",
      "user": "https://kf.kobotoolbox.org/api/v2/users/project_owner/",
      "permission": "https://kf.kobotoolbox.org/api/v2/permissions/change_submissions/",
      "label": "Edit submissions"
    },
    {
      "url": "https://kf.kobotoolbox.org/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/permission-assignments/pwoCoBBLmyWsdF2dXPBaHt/",
      "user": "https://kf.kobotoolbox.org/api/v2/users/project_owner/",
      "permission": "https://kf.kobotoolbox.org/api/v2/permissions/delete_submissions/",
      "label": "Delete submissions"
    },
    {
      "url": "https://kf.kobotoolbox.org/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/permission-assignments/pqDGr7M7au4NsFiuKkEeTr/",
      "user": "https://kf.kobotoolbox.org/api/v2/users/project_owner/",
      "permission": "https://kf.kobotoolbox.org/api/v2/permissions/manage_asset/"
    }
  ]
}
```
```

--------------------------------

### Generate RSA Private Key

Source: https://support.kobotoolbox.org/encrypting_forms.html?highlight=encryption

Use this command to generate a 2048-bit RSA private key and save it to a PEM file. Ensure OpenSSL is installed and accessible in your system's PATH or navigate to its bin directory.

```bash
openssl genpkey -out MyPrivateKey.pem -outform PEM -algorithm RSA -pkeyopt rsa_keygen_bits:2048
```

--------------------------------

### Constraint for Date Questions

Source: https://support.kobotoolbox.org/constraints_xls.html

Use the `date()` format to specify date constraints. This example ensures the entered date is after January 1, 2021.

```XLSForm
type | name | label | constraint
date | start_date | When did you start? | . > date('2021-01-01')
```

--------------------------------

### Count All Rows in Parent Form

Source: https://support.kobotoolbox.org/dynamic_data_attachment_formbuilder.html

Use this XPath in the question label of a Calculate question to get the total number of rows in the parent form.

```xpath
count(instance('parent')/root/data)
```

--------------------------------

### Basic Text Styling in Note Questions

Source: https://support.kobotoolbox.org/note_questions.html

Use Markdown for basic text styling like italics and bold within note questions. Ensure correct syntax for emphasis.

```markdown
*italics*
_italics_
```

```markdown
**bold**
__bold__
```

--------------------------------

### Metadata Endpoints

Source: https://support.kobotoolbox.org/migrating_api.html

This section details the mapping of metadata endpoints from v1 to v2. Note that v2 scopes media files per project and introduces pagination, unlike v1 which returns all results at once. Only media files are supported in v2, while other metadata types from v1 are not ported.

```APIDOC
## Metadata Endpoints

### Description
These endpoints return a flat list of all media files associated with the current user, across all deployed projects or a specific project. In `v2`, media files are now scoped per project. As with other endpoints, `v2` introduces pagination, whereas `v1` returns all results in a single response.

### Endpoint Mapping

`v1` Endpoint | `v2` Equivalent
---|---
`/api/v1/metadata` | `/api/v2/assets/{asset_uid}/files/`
`/api/v1/metadata/<pk>` | `/api/v2/assets/{asset_uid}/files/{file_uid}/`

**Note:** `v2` only supports media files: `media` from `v1` is mapped to `form_media` in `v2`. **Other metadata types** from `v1` (e.g., `doc`, `mapbox_layer`, `source` etc.) have not been ported to `v2`.

### Field Mapping

`v1` Field | `v2` Equivalent
---|---
`id` | `uid`
`data_type` | `file_type`
`xform` | _N/A_
`data_value` | `metadata.filename` or `metadata.redirect_url`
`data_filename` | `metadata.filename`
`data_file` | `content`
`data_file_type` | `metadata.mimetype`
`file_hash` | `metadata.hash`
`from_kpi` | _N/A_

### Example v1 Response
```json
{
  "id": 271,
  "xform": 374,
  "data_value": "goose.jpg",
  "data_type": "media",
  "data_file": "/project_owner/form-media/b44a7c2cd0f244e6b405821582364657/goose.jpg",
  "data_file_type": "image/jpeg",
  "file_hash": "md5:93fb96bced1e3b392abfc22934afe51a",
  "url": "https://kc.kobotoolbox.org/api/v1/metadata/271?format=json",
  "from_kpi": true,
  "data_filename": "goose.jpg"
}
```

### Equivalent v2 Response
```json
{
  "uid": "afoeCcF3AcGNpWUoM6bvKj9",
  "asset": "http://kf.kobo.localhost/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/",
  "file_type": "form_media",
  "content": "http://kf.kobo.localhost/api/v2/assets/a4etXeWtqcoodSxLV8a6Uq/files/afoeCcF3AcGNpWUoM6bvKj9/content/",
  "metadata": {
    "hash": "md5:93fb96bced1e3b392abfc22934afe51a",
    "filename": "goose.jpg",
    "mimetype": "image/jpeg"
  },
  ...
}
```
```
Tokens:
Raw