Attachments and Media

Lists attachments of all xforms

GET /api/v1/media/

Example

curl -X GET https://api.ona.io/api/v1/media

Response

[
    {
        "download_url": "http://api.ona.io/api/v1/media/1.jpg",
        "small_download_url": "http://api.ona.io/api/v1/media/1-small.jpg",
        "medium_download_url": "http://api.ona.io/api/v1/media/1-medium.jpg",
        "filename": "doe/attachments/1408520136827.jpg",
        "id": 1,
        "instance": 1,
        "mimetype": "image/jpeg",
        "url": "http://api.ona.io/api/v1/media/1",
        "xform": 1,
    },
    ...
]

Paginate attachment

Returns a list of attachments using page number and the number of items per page. Use the page parameter to specify page number and page_size parameter is used to set the custom page size.

Example

curl -X GET https://api.ona.io/api/v1/media.json?page=1&page_size=4

Retrieve details of an attachment

  GET /api/v1/media/{pk}

Example

curl -X GET https://api.ona.io/api/v1/media/1

Response

{
    "download_url": "http://api.ona.io/api/v1/media/1.jpg",
    "small_download_url": "http://api.ona.io/api/v1/media/1-small.jpg",
    "medium_download_url": "http://api.ona.io/api/v1/media/1-medium.jpg",
    "filename": "doe/attachments/1408520136827.jpg",
    "id": 1,
    "instance": 1,
    "mimetype": "image/jpeg",
    "url": "http://api.ona.io/api/v1/media/1",
    "xform": 1,
}

Retrieve an attachment file

GET /api/v1/media/{pk}.{format}
curl -X GET https://api.ona.io/api/v1/media/1.png -o a.png

Alternatively, if the request is made with an Accept header of the content type of the file the file would be returned e.g

GET /api/v1/media/{pk} Accept: image/png

Example

curl -X GET https://api.ona.io/api/v1/media/1 -H "Accept: image/png" -o a.png

Lists attachments of a specific xform

GET /api/v1/media/?xform={xform}

Example

curl -X GET https://api.ona.io/api/v1/media?xform=1

Response

[
    {
        "download_url": "http://api.ona.io/api/v1/media/1.jpg",
        "small_download_url": "http://api.ona.io/api/v1/media/1-small.jpg",
        "medium_download_url": "http://api.ona.io/api/v1/media/1-medium.jpg",
        "filename": "doe/attachments/1408520136827.jpg",
        "id": 1,
        "instance": 1,
        "mimetype": "image/jpeg",
        "url": "http://api.ona.io/api/v1/media/1",
        "xform": 1,
    },
    ...
]

Lists attachments of a merged dataset

GET /api/v1/media/?merged_xform={merged_xform_id}

Example

curl -X GET https://api.ona.io/api/v1/media?merged_xform=1

Response

[
    {
        "url": "http://testserver/api/v1/media/1",
        "filename": "bob/attachments/1_a/test-image_qdCeDHO.png",
        "mimetype": "image/png",
        "field_xpath": null,
        "id": 1,
        "xform": 1,
        "instance": 1,
        "download_url": "http://testserver/api/v1/files/1?filename=bob/attachments/1_a/test-image_qdCeDHO.png",
        "small_download_url": "http://testserver/api/v1/files/1?filename=bob/attachments/1_a/test-image_qdCeDHO.png&suffix=small",
        "medium_download_url": "http://testserver/api/v1/files/1?filename=bob/attachments/1_a/test-image_qdCeDHO.png&suffix=medium"
    },
    ...
]

Lists attachments of a filtered dataset

Pass a dataview parameter to the media endpoint. Filtered datasets are internally known as DataViews. The response contains attachments from selected media columns and matching submissions. Use the returned download URL, which includes the dataview parameter, to download an attachment.

GET /api/v1/media/?dataview={filtered_dataset_id}

Example

curl -X GET https://api.ona.io/api/v1/media?dataview=1

Response

[
    {
        "url": "http://testserver/api/v1/media/1",
        "filename": "bob/attachments/1_a/test-image_qdCeDHO.png",
        "mimetype": "image/png",
        "field_xpath": null,
        "id": 1,
        "xform": 1,
        "instance": 1,
        "download_url": "http://testserver/api/v1/files/1?filename=bob/attachments/1_a/test-image_qdCeDHO.png&dataview=1",
        "small_download_url": "http://testserver/api/v1/files/1?filename=bob/attachments/1_a/test-image_qdCeDHO.png&suffix=small&dataview=1",
        "medium_download_url": "http://testserver/api/v1/files/1?filename=bob/attachments/1_a/test-image_qdCeDHO.png&suffix=medium&dataview=1"
    },
    ...
]

Lists attachments of a specific instance

GET /api/v1/media?instance={instance}

Example

curl -X GET https://api.ona.io/api/v1/media?instance=1

Response

[
    {
        "download_url": "http://api.ona.io/api/v1/media/1.jpg",
        "small_download_url": "http://api.ona.io/api/v1/media/1-small.jpg",
        "medium_download_url": "http://api.ona.io/api/v1/media/1-medium.jpg",
        "filename": "doe/attachments/1408520136827.jpg",
        "id": 1,
        "instance": 1,
        "mimetype": "image/jpeg",
        "url": "http://api.ona.io/api/v1/media/1",
        "xform": 1,
    },
    ...
]

Lists of attachment filter by attachment type

GET /api/v1/media?xform={xform_id}&?type={attachment_type}

You can use this to get attachment specific to the attachment type.

Example

curl -X GET https://api.ona.io/api/v1/media?type=image

Response

[
    {
    "url": "https://api.ona.io/api/v1/media/1",
    "filename": "doe/attachments/4266445458362.png",
    "mimetype": "image/png",
    "field_xpath": null,
    "id": 1,
    "xform": 1,
    "instance": 1,
    "download_url": "http://api.ona.io/api/v1/media/1.png",
    "small_download_url": "http://api.ona.io/api/v1/media/1-small.png",
    "medium_download_url": "http://api.ona.io/api/v1/media/1-medium.png",
    },
    ...
]

Supported media attachment types that could be used to filter include:

  • video

  • audio

  • file

Retrieve attachment count for a form

Returns the total number of attachments for a form

GET /api/v1/media/count?xform={xform_id}

Example

curl -X GET https://api.ona.io/api/v1/media/count?xform=1

Response

{"count": 1}