Custom endpoints & auth for aggregate replacement

Hi All! I'm in the process of building a simple "Aggregate replacement" API / server in NodeJS to

  • receive ODK Collect form submissions, and
  • replicate the endpoints used by ODK Collect as closely as possible.

I'm struggling to find the endpoint Collect uses to download the custom media that accompanies a form. In Collect > Server settings > Type = Other, there are only two options for endpoints - "Form list path" and "Submission Path". The form list contains only direct links to form definitions. My questions are:
Q - how does aggregate expose the media files required by a form to Collect for download?
Q - how does collect authenticate with aggregate, if one was to replicate this? (basic / digest / other? )

The information is documented if you search for it. You are going to be interested in the Collect-Aggregate API.

A - Media manifests through form list
A - http digest and basic auth over TLS

Hi Brent, thank you for your response.

I may have been slightly vague in my first post - I've been looking through the docs carefully - the only mention of the way "other media" is downloaded with a form definition by Collect is on the Javarosa FormListAPI wiki page. The API docs show an example form list response as follows:

<xforms xmlns="">
    <name>Form with zero or more additional files</name>
    <descriptionText>A possibly very long description of the form</descriptionText>

This makes sense - there is a manifestUrl tag which points to the extra files. However, the xml response by the /formList endpoint on odk aggregate does not follow this specification. Instead I'm getting:

    <form url="">Fisher_Logbook_v2_0</form>

From what I can see, the only reference to this specfic functionality on the github wiki page is the Download forms and media files section on the Briefcase Aggregate API page.

I'm asking here on the forum short of having to delve into the ODK Collect source myself.

First, don't be shy about looking at the source code. It's the only 100% reliable source of truth when it comes to these types of questions. However, having reverse engineered the protocol for Aggregate and Briefcase myself recently, I can say the docs are fairly accurate.

One reason you may be seeing differences is that if you try to use a normal web browser to inspect the protocol, you're not going to observe what a compliant OpenRosa client would. You need to send the OpenRosa headers for Aggregate to speak the full protocol. You're likely seeing the fallback compatibility mode for pre-OpenRosa clients.



I believe that what you're looking for is at There's a project underway to verify that documentation and make it available at so hopefully it will soon be easier to find.

The Briefcase API is another animal that you probably won't need to touch unless you also want Briefcase to be able to pull from your server. Collect does not interact with it directly.

edit: now I see that it's the doc you had linked to in the first place. That's the one to look at and @Batkison's explanation of why you're not seeing the expected response sounds right.

You might be interested in taking a look at OpenMapKitServer. It's the lightweight NodeJS server component of OpenMapKit that handles the collection and aggregation of OpenStreetMap and OpenDataKit data. But it works even if you don't have an OMK part to your survey.


Hi everyone, thanks for the replies. For anyone who sees this thread in the future, I needed to set the OpenRosa header as Brent suggested.

"X-OpenRosa-Version" : "1.0"

Thanks for all the help! @danbjoseph I'll definitely take a look at the odk portion of OpenMapKitServer, this is exactly what I've been looking for.


Where can I access the link is broken.

Hi @tmndungu, welcome to the ODK forum, we're glad you're here! Thanks for adding a picture to your profile, we think it helps build community. If you get a chance, we'd appreciate it if you introduce yourself on this other forum thread.

I believe those docs have been transitioned to and can be found at (and with the Form List API docs at

1 Like

Hi @danbjoseph, thank you for the warm welcome and quick response to my query. I have put a brief intro hope its sufficient.

1 Like