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

You’ll ned to pass a dataview parameter to the media endpoint. Filtered datasets are internally known as dataviews.

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",
        "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 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}