Changelog

Here major and breaking changes to the API are listed by version.

ODK Central v2025.3

Added:

• New endpoint GET /projects/:id/datasets/:name/entities/creators to retrieve a list of all Actors who have created Entities in a Dataset, sorted by display name.

• Bulk delete Entities endpoint for deleting multiple Entities at once.

• Bulk restore Entities endpoint for restoring multiple soft-deleted Entities at once.

• Endpoints for getting submissions' and entities' geodata in GeoJSON format.Their current primary use case is to deliver data for the map in Central.

  ⚠️ This API will likely change in a future release.

  The endpoints are:

  • GET /projects/:id/datasets/:name/entities.geojson
  • GET /projects/:id/forms/:xmlFormId/submissions.geojson

Changed:

• Download Dataset API now supports $search query parameter.
• Added deleted query parameter to GET /projects/:id/forms/:xmlFormId/submissions to retrieve deleted submissions.

Changed:

• GET /users and GET /users/:actorId now include lastLoginAt field.

ODK Central v2025.2

Added:

• Datasets now have a boolean property named ownerOnly. This is a flag that has an effect on Actors who only have access to the Dataset CSV file via linked Form Attachments: App Users, Web Users with a role of Data Collector, and Public Access Links. If ownerOnly is true, and the Actor is one of the above, then only Entities created by the Actor will be downloaded to the OpenRosa client.

Changed:

• Entities OData now supports $search query parameter.
• Form attachment manifest API returns type="approvalEntityList" in the mediaFile element for the Datasets that require Submission approval to create Entities.

ODK Central v2025.1

Added:

• RESTORE endpoint for Entities.
• Entities that have been soft-deleted for 30 days will automatically be purged.
• Entities Odata now returns __system/deletedAt. It can also be used in $filter, $sort and $select query parameters.
• Integrity endpoint for the Entity list.
• Get Form metadata by EnketoId

Changed:

• webformsEnabled boolean flag is added to Forms APIs that enables use of ODK Web Forms instead of Enketo.
• Draft Submission can be created using draft token by adding /test/{token} to Creating a draft Submission endpoint.
• Dataset Metadata now includes a new property, lastUpdate, which is the timestamp of the latest modification to the datasets or its entities.
• After a file is uploaded for a Form Attachment via the POST endpoint, the response is now the updated Attachment.
• userAgent and deviceId longer than 255 characters will be truncated in Submissions APIs

ODK Central v2024.3

Added:

• Endpoints for managing User Preferences, mainly to be used by the frontend.

Changed:

• Submissions Odata now returns __system/deletedAt. It can also be used in $filter, $sort and $select query parameters.
• Dataset (Entity List) properties with the same name but different capitalization are not allowed.
• Form Attachments for both published Forms and draft Forms now return a property representing the hash of the attachment file.

ODK Central v2024.2

Added:

• Submission Delete!
  • New DELETE and RESTORE endpoints for submissions!
  • Submissions that have been soft-deleted for 30 days will automatically be purged.
• Additional properties on certain responses:
  • Extended metadata for Forms includes a new property publicLinks, which is the number of Public Links that can submit to the Form.
  • Data for Entity versions now includes the properties branchId, trunkVersion, and branchBaseVersion for supporting offline functionality.

ODK Central v2024.1

Added:

• Bulk Entity Creation!
  • The existing Entity Create endpoint now also accepts a list of Entities to append to a Dataset.
  • The uuid property is no longer required and Central will generate a UUID for each new Entity if needed.
• Datasets (Entity Lists) and Properties can now be added via the API instead of only through Forms.
• OData Data Document for requests of Submissions and Entities now allow use of $orderby.
• ETag headers on all Blobs.

Changed:

• The Entity Create endpoint will now generate a UUID if the uuid parameter is not provided.

ODK Central v2023.5

Added:

• Central now supports Entity Updates via Submissions as part of our continued work on Entity-Based Data Collection!
  • Submissions for Entity Updates specify which properties/label to update with new values and an Entity's target baseVersion, which is used to track conflicts
• Entities accessed via the API have additional information about conflicts (when multiple Submissions update the same Entity)
  • Each Entity now has a conflict field, which is either:
    • null. The Entity does not have conflicting versions.
    • soft. The Entity has a version that was based on a version other than the version immediately prior to it. (The specified baseVerson was not the latest version on the server.)
    • hard. The Entity has a version that was based on a version other than the version immediately prior to it. Further, that version updated the same property as another update.
    • If an Entity has a conflict, it can be marked as resolved. After that, the conflict field will be null until a new conflicting version is received.
  • Each Entity Version (currentVersion or list of versions) has new fields baseVersion, dataReceived, and conflictingProperties
• Datasets extended metadata now has a conflicts field, which counts number of Entities currently in conflict
• Entity conflicts can be resolved using the existing PATCH endpoint, with or without new data
• New relevantToConflict query parameter on GET entities/:uuid/versions

Changed:

• Dataset entity list entities.csv can now be filtered
• Entity Update PATCH endpoint now expects baseVersion query parameter or force flag

ODK Central v2023.4

Added:

• DELETE /sessions/current logs out the current session.

Changed:

• If single sign-on (SSO) with Open ID Connect (OIDC) is enabled then HTTP Basic Authentication and login with POST /v1/session are disabled.
• GET /v1/projects returns list of Datasets if ?dataset=true parameter is provided in the request.
• Version number of the Entity is added to the response of GET /projects/{projectId}/datasets/{name}/entities.csv and Entity OData feed

ODK Central v2023.3

Added:

• New endpoint PATCH /projects/:id/datasets/:name to change whether approval of Submission is required to create an Entity.

• New Entities endpoints for richer Entity-Based Data Collection workflows. These endpoints provide ways of accessing Entities, as well as the ability to create, update and soft-delete Entities via the API!

  • New endpoint GET /projects/:id/datasets/:name/entities for listing Entities within a Dataset.
  • New endpoint GET /projects/:id/datasets/:name/entities/:uuid for getting the metadata, or details, about a specific Entity.
  • New endpoint GET /projects/:id/datasets/:name/entities/:uuid/versions for listing the versions of an Entity.
  • New endpoint GET /projects/:id/datasets/:name/entities/:uuid/diffs for getting the changes between versions of an Entity.
  • New endpoint GET /projects/:id/datasets/:name/entities/:uuid/audits for getting the server audit logs about a specific Entity.
  • New endpoint POST /projects/:id/datasets/:name/entities for creating an Entity from JSON.
  • New endpoint PATCH /projects/:id/datasets/:name/entities/:uuid for updating the data or label of an Entity.
  • New endpoint DELETE /projects/:id/datasets/:name/entities/:uuid for soft-deleting an Entity.

Changed:

• ETag support has been added for Download Dataset and Download Form Attachment.
• The format of Download Dataset was changed to more closely match the OData Dataset format.
• In the OData Dataset Service, name was removed because it is a duplication of an __id representing an Entity's UUID.
• The properties returned by the Dataset Metadata endpoint each now include a field odataName, which represents the way the property name will be sanitized and outputted for OData.

ODK Central v2023.2

Added:

• New OData Dataset Service for each Dataset that provides a list of Entities.

Changed:

• The response of GET, POST, PUT and PATCH methods of Submissions endpoint has been updated to include metadata of the currentVersion of the Submission.

ODK Central v2023.1

Added:

• New endpoint GET /projects/:id/datasets/:name to get the metadata of a Dataset

Changed:

• GET /projects/:id/datasets now supports X-Extended-Metadata header to retrieve number of Entities in the Dataset and timestamp of the last Entity

• $select in OData now supports selecting complex type(groups)

• Creating a form can now return workflow warnings

Removed:

• Scheduled backups to Google Drive are no longer supported. As a result, backups are no longer configurable. It is no longer possible to get or terminate a backups configuration or to use a backups configuration to GET a Direct Backup. For more information about these changes, please see this topic in the ODK Forum.

ODK Central v2022.3

Added:

• Introducing Datasets as the first step of Entity-Based Data Collection! Future versions of Central will build on these new concepts. We consider this functionality experimental and subject to change in the next release.

  • Forms can now create Datasets in the project, see Creating a New Form and the ODK XForms specification for details.
  • New endpoint GET /projects/:id/datasets for listing Datasets of a project.
  • New endpoint GET /projects/:id/datasets/:name/entities.csv to download the Dataset as a CSV file.
  • New endpoints for Related Datasets to see the Datasets affected by published and unpublished Forms.
  • New endpoint PATCH .../attachments/:name to link/unlink a Dataset to a Form Attachment.

• OData Data Document requests now allow limited use of $select.

Changed:

• The following endpoints have changed with the addition of Datasets:

  • The Extended Project endpoint now returns the datasets count for the Project.
  • The Extended Form endpoint now returns the entityRelated flag if the form defines a Dataset schema.
  • DELETE .../draft/attachments/:name will unlink the Dataset if there's a Dataset link to the attachment.
  • GET .../draft/attachments/:filename will return the Dataset as a CSV file if the attachment is linked to a Dataset.
  • GET .../draft/attachments returns two additional flags blobExists and datasetExists.
  • In the OpenRosa Form Manifest, if a Form Attachment is linked to a Dataset, then the value of hash is an MD5 sum derived from the last updated timestamp of the Dataset. hash is not the MD5 sum for the content of the Dataset CSV file.

ODK Central v1.5.3

Removed:

• It is no longer possible to initiate a new backups configuration (POST /v1/config/backups/initiate) or to verify one (POST /v1/config/backups/verify). However, for now, if there is an existing configuration, it is still possible to get it or terminate it. If the existing configuration is terminated, it will not be possible to set up a new configuration. Note that it is still possible to download a Direct Backup. For more information about this change, please see this topic in the ODK Forum.

ODK Central v1.5

ODK Central v1.5 adds editable Project descriptions as well as more detailed information about Forms and Submissions when listing Projects.

Added:

• New description field returned for each Project that can be set or updated through POST/PATCH/PUT on /projects/…

  • Note that for the PUT request, the Project's description must be included in the request. Read more.

• Form extended metadata now includes a reviewStates object of counts of Submissions with specific review states.

  • e.g. {"received":12, "hasIssues":2, "edited":3}

• New ?forms=true option on Project Listing that includes a formList field containing a list of extended Forms (and the review state counts described above) associated with that Project.

ODK Central v1.4

ODK Central v1.4 enables additional CSV export options and creates an API-manageable 30 day permanent purge system for deleted Forms. Previously, deleted Forms were made inaccessible but the data was not purged from the database.

Added:

• New ?groupPaths and ?splitSelectMultiples options on CSV export paths which aim to replicate ODK Briefcase export behavior. One simplifies nested path names and the other breaks select multiple options out into multiple columns.

• New ?deletedFields option on CSV export which exports all previously known and deleted fields and data on the form.

• Deleted Forms (either by API DELETE or through the web interface) are now placed in a 30 day hold, after which an automated process will permanently delete all data related to the Form.

  • You can see Forms in the 30 day wait by listing Forms with ?deleted=true. You can also see them in the Trash section on the web interface.
  • POST /projects/…/forms/…/restore to restore a Form that hasn't yet been permanently purged.

• Additional metadata field 'formVersion' on CSV export, OData feed, and extended Submission Version request which reports the version of the Form the Submission was originally created with.

• Additional metadata fields userAgent and deviceId tracked and returned for each Submission Version.

  • These are collected automatically upon submission through transmitted client metadata information, similar to the existing deviceId field returned with each Submission.

ODK Central v1.3

ODK Central v1.3 adds granular Submission edit history, as well as opt-in usage reporting to the Central team.

Added:

• GET /projects/…/forms/…/submissions/…/diffs will return the changes between each version of a Submission.

• You can set the Usage Reporting configuration to choose whether the server will share anonymous usage data with the Central team. By default, no usage information will be sent at all.

• You can also preview the Usage Report to see exactly what information would be sent in a Usage Report.

Changed:

• Additional actions are now logged in the Server Audit Log:

  • A user.session.create action will be logged when a User logs in using Session Authentication.
  • A form.submissions.export action will be logged when a User exports Form Submissions to CSV.

• The Submission update timestamp is now included in OData (as __system/updatedAt). Resources that accept the $filter query parameter can be filered on __system/updatedAt.

• All groups are now included in OData, even if they are not relevant. For more information, see this post in the ODK Forum.

• The Content-Disposition header now specifies the filename* parameter, allowing filenames to contain Unicode.

ODK Central v1.2

ODK Central v1.2 adds submission editing, review states, and commenting.

Added:

• POST /projects/…/submission now accepts ecosystem-compatible submission updates over OpenRosa, using the deprecatedID.

• REST-friendly submission updates by PUTing XML directly to the submission resource path.

• GET /projects/…/forms/…/submissions/…/edit will now redirect the authenticated user (after some thought) to an Enketo-powered webform for editing the submission.

• There is now a subresource /projects/…/forms/…/submissions/…/versions to get all versions of a submission, and details about each one, including submitted media files.

• There is now a subresource /projects/…/forms/…/submissions/…/comments which allows very simple comment creation (POST) and listing (GET) on a submission.

• Submissions now have a reviewState property which can be updated via PATCH /projects/…/forms/…/submissions.

• You can now provide X-Action-Notes on any API request that might generate audit logs, to leave a note on those log entries.

• GET /projects/…/forms/…/submissions/…/audits will return just audit logs pertaining to that submission.

• OData queries may now request ?expand=* to request all nested data structures inline. Only * is accepted.

• OData $filter queries may now reference the new __system/reviewState metadata field.

• There is now a data download path you can direct users to which eases media file access.

• Submissions now have an instanceName field which reflects the <instanceName/> tag on the submitted XML.

• The REST submission endpoint now accepts optional ?deviceID= just like the OpenRosa submission endpoint.

Changed:

• Unpublished Forms (Forms that only have a Draft and have never been published) will now appear with full details in GET /projects/…/forms. Previously, values like name would be null for these Forms. You can still identify unpublished Forms as they will have a publishedAt value of null.

• Date and Boolean OData types are now given as date and boolean rather than text.

• Broke Forms and Submissions section apart into two below. This may break some links.

ODK Central v1.1

ODK Central v1.1 adds minor new features to the API.

Added:

• POST/GET /backup, will immediately perform a backup of the database and return the encrypted backup.

• POST/GET /projects/…/forms/…/submissions.csv, which allows download of the root table (excluding repeat data) as CSV, without a zipfile.

• POST/GET /projects/…/forms/…/submissions.csv.zip now allows ?attachments=false to exclude attachments.

• OData Data Document requests now allow limited use of $filter.

• The various submissions.csv.* endpoints also allow $filter, using the same limited OData syntax.

• GET /projects/…/forms/…/submissions/submitters which returns submitter Actors for a given Form.

Fixed:

• Documented the deviceId property of submission, which was added in version 0.4.

ODK Central v1.0

ODK Central v1.0 adds Public Links to the API, and makes one minor breaking change.

Added:

• The new Public Link resource lets you create Public Access Links, granting anonymous browser-based access to submit to your Forms using Enketo.

Changed:

• The non-extended App User response no longer includes a createdBy numeric ID. To retrieve the creator of an App User, request the extended response.

• We no longer reject the request if multiple authentication schemes are presented, and instead document the priority order of the different schemes here.

ODK Central v0.9

ODK Central v0.9 does not change the API except for one minor breaking change.

Changed:

• The OpenRosa Form Listing API has been modified to always require authentication. If a valid Actor is authenticated at all, a form list will always be returned, filtered by what that Actor is allowed to access.

ODK Central v0.8

ODK Central v0.8 introduces Draft Forms, publishing, and archived Form versions, which has a significant breaking impact on the existing API. The changes should be straightforward to adapt to, however. If you are currently creating Forms with POST /projects/…/forms, you may wish to add ?publish=true to skip the Draft state and mimic the old behaviour. If you are using the API to push Form Attachments onto Forms, you'll only be able to do so now in draft state, at /projects/…/forms/…/draft/attachments.

Added:

• Draft Forms and publishing, and archived Form versions.

  • This includes a subresource at /projects/…/forms/…/draft,
  • and another at /projects/…/forms/…/versions,
  • and a new collection of OpenRosa endpoints, under /test/…/projects/…/forms/…/draft, for submitting test submissions to the draft version of the form.

• GET /projects/…/forms/…/fields, which replaces GET /projects/…/forms/….schema.json.

• App User responses now include the projectId they are bound to.

Changed:

• As part of the Draft Forms change, the read/write endpoints for Form Attachments have been moved to the Draft Form state and subresource, at /projects/…/forms/…/draft/attachments.

Removed:

• GET /projects/…/forms/….schema.json has been removed in favor of GET /projects/…/forms/…/fields.

Fixed:

• Documented GET /projects/…/forms/….xls(x), which was added in 0.7.

ODK Central v0.7

Added:

• Form-specific Assignments resource at projects/…/forms/…/assignments, allowing granular role assignments on a per-Form basis.

  • Relatedly, the OpenRosa Form Listing API no longer rejects requests outright based on authentication. Rather, it will only return Forms that the authenticated user is allowed to view.
  • A new summary API GET /projects/…/assignments/forms which returns all assignments on all Forms within a Project, so you don't have to request this information separately for each Form.

• PUT /projects/:id, which while complex allows you to update many Forms' states and assignments with a single transactional request.

• POST /projects/…/forms now allows upload of .xls and .xlsx XLSForm files. The correct MIME type must be given.

• GET /users/?q will now always return user details given an exact match for an email, even for users who cannot user.list. The request must still be authenticate as a valid Actor. This allows non-Administrators to choose a user for an action (eg grant rights) without allowing full search.

Changed:

• Newly created App Users are no longer automatically granted download and submission access to all Forms within their Project. You will want to use the Form Assignments resource to explicitly grant app-user role access to the Forms they should be allowed to see.

Fixed:

• Correctly documented keyId property on Projects.

ODK Central v0.6

Added:

• GET /audits Server Audit Log retrieval resource.

• Project Managed Encryption:

  • POST /projects/…/key to enable project managed encryption.
  • Both submission intake methods (OpenRosa and REST) now support encrypted submissions.
  • GET /projects/…/forms/…/submissions/keys to get a list of encryption keys needed to decrypt all submitted data.
  • ?{keyId}={passphrase} option on GET /projects/…/forms/…/submissions.csv.zip to get a decrypted archive given the passphrase.
  • POST /projects/…/forms/…/submissions.csv.zip to provide a browser-secure (no querystring) method of accessing the above GET .csv.zip resource.
  • OData and .csv.zip data responses now contain an additional status system column.

• Form resource data now includes projectId and 'keyId'.

• ?odata=true option on GET /projects/…/forms/….schema.json to sanitize the field names to match the way they will be outputted for OData.

Changed:

• GET /projects/…/forms/…/attachments now always returns updatedAt. There is no longer a separate Extended Metadata response for this resource.

• The Submission response format now provides the submitter ID at submitterId rather than submitter. This is so that the Extended responses for Submissions can use submitter to provide the full Actor subobject rather than replacing it. This brings the response format to be more similar to the other Extended formats.

• OData resources now namespace the __system schema information under org.opendatakit.submission rather than alongside user metadata (org.opendatakit.user.*). The actual returned data has not changed; this is purely a metadata document change.

Removed:

• The Extended responses for Forms and Submissions no longer include an xml property. To retrieve Form or Submission XML, use the dedicated endpoints for Form XML and Submission XML.

ODK Central v0.5

Added:

• Roles and Assignments resources at /roles, /assignments, and /projects/…/assignments.

• Optional ?q= querystring parameter on Users GET listing, for searching users.

• Extended GET /users/current: added verbs list of verbs the authenticated Actor may perform server-wide.

• Extended Project GET: added appUsers count of App Users and verbs list of verbs the authenticated Actor may perform upon/within the Project.

• User DELETE.

• Projects now have an archived flag which may be set to clear a Project out of the way without deleting it.

Changed:

• Removed autopromotion of Users to Administrator upon creation (POST). Roles must be assigned separately and explicitly.

• Changed Project Listing (GET /projects) to never reject based on authentication; instead it filters the response based on the access of the authenticated Actor.

• Changed xmlFormId/version conflict errors on POSTing a new Form from a 400 code to a 409 code.

• Changed all remaining textual references to "Field Keys" to "App Users" in the documentation.

Fixed:

• Corrected Actor documentation to match reality: removed meta field and added type field.

• Corrected Extended Form documentation: added createdBy field.

• Corrected Backup Config documentation. It was almost entirely wrong.

• Added Submission POST REST documentation.

ODK Central v0.4

Added:

• Projects resource at /projects.

• Submission XML resource fetch at GET /projects/…/forms/…/submissions/….xml.

• Submission attachment management over REST, at the /attachments subresource within Submissions.

Changed:

• Renamed all /field-keys routes to /app-users.

• Moved all Forms, Submissions, and App User resources under Projects (e.g. /forms/simple would now be something like /projects/1/forms/simple).

• Changed GET Form to not return Form XML. The Extended Metadata version of those requests will give the XML.

• Changed both OpenRosa and REST Submission creation processes to create and accept only the attachment filenames that are indicated to exist by the Submission XML.

• Changed GET Submission Attachemnts listing to return an array of objects containing attachment details rather than an array of filename strings.

Did this page help you?

Selecting an option will open a 1-question survey

👍 Yes 👎 No