Sign in

v51

latestOpenAPI 3.0.1raw.githubusercontent.com2026-08-0118684573.2 KB
Dataset Management

Update Dataset Access Filters and Metadata

You can use this endpoint to update approvalRequired, ownerOnly, and accessFilter. However, you cannot update other properties, such as name.

The approvalRequired flag controls the Entity creation flow. If it is true, then the Submission must be approved before an Entity can be created from it. If it is false, then an Entity is created as soon as the Submission is received by ODK Central. By default, approvalRequired is false for Datasets created after v2023.3. Datasets created prior to that will have approvalRequired set to true.

The accessFilter field filters which Entities are visible to App Users and Public Links when they download the Dataset via a linked Form Attachment. When accessFilter is present, it takes precedence over the legacy ownerOnly flag.

accessFilter valueBehavior
nullNo restrictions; all Entities are visible.
{ "type": "ownerOnly" }Each Actor only sees Entities they created.
{ "type": "property", "rules": [...] }Each Actor only sees Entities where the specified Dataset property matches their Actor property value. Multiple rules are ANDed together.

The legacy ownerOnly boolean field is still accepted when accessFilter is absent, and behaves as before. If ownerOnly is true, and the Actor using the OpenRosa client only has access to the Dataset CSV file via linked Form Attachments, then only Entities created by the Actor will be included. This is true of App Users, Web Users with a role of Data Collector, and Public Access Links. If ownerOnly is false, or if the Actor has direct access to the Dataset CSV file, then all Entities will be included. Accessing the Dataset CSV file via linked Form Attachments using a draftToken will also retrieve all Entities; this functionality assumes the draftToken is used by Actors with full dataset access, such as Project Managers and System Administrators. By default, ownerOnly is false.

patch/v1/projects/{projectId}/datasets/{name}

Path parameters

projectIdnumber required

The numeric ID of the Project

namestring required

Name of the Dataset

Request body

approvalRequiredboolean

Control whether a Submission should be approved before an Entity is created from it.

ownerOnlyboolean

Legacy flag. If ownerOnly is true, and an Actor only has access to the Dataset CSV file via linked Form Attachments, then only Entities created by the Actor will be downloaded to the OpenRosa client. Ignored when accessFilter is also present.

Example request

{
  "accessFilter": {
    "type": "property",
    "rules": [
      {
        "datasetProperty": "state",
        "actorProperty": "region"
      }
    ]
  }
}

Response

OK

namestring required

The name of the Dataset

createdAtstring required

ISO date format.

projectIdnumber required

The numerical ID of the Project that the Dataset belongs to.

approvalRequiredboolean

Control whether a Submission should be approved before an Entity is created from it.

ownerOnlyboolean

Legacy flag. If ownerOnly is true, and an Actor only has access to the Dataset CSV file via linked Form Attachments, then only Entities created by the Actor will be downloaded to the OpenRosa client. Superseded by accessFilter when set.

lastUpdatestring

ISO date format. The timestamp of the most recent change to the dataset or its entities

Example response

{
  "name": "people",
  "createdAt": "2018-01-19T23:58:03.395Z",
  "projectId": 1,
  "approvalRequired": true,
  "accessFilter": {
    "type": "property",
    "rules": [
      {
        "datasetProperty": "state",
        "actorProperty": "region"
      }
    ]
  },
  "lastUpdate": "2020-10-10T03:04:51.695Z",
  "linkedForms": [
    {
      "xmlFormId": "simple",
      "name": "Simple"
    }
  ],
  "sourceForms": [
    {
      "xmlFormId": "simple",
      "name": "Simple"
    }
  ],
  "properties": [
    {
      "name": "the.age",
      "odataName": "the_age",
      "publishedAt": "2018-01-21T00:04:11.153Z",
      "forms": [
        {
          "xmlFormId": "simple",
          "name": "Simple"
        }
      ]
    }
  ]
}