System Endpoints

There are some resources available for getting or setting system information and configuration. For example, you can set the Usage Reporting configuration for the server, retrieve the Server Audit Logs, or perform a Direct Backup.

System Configuration

(introduced: version 1.3)

Getting the current Usage Reporting configuration

GET /v1/config/analytics

If the Usage Reporting configuration is not set, this endpoint will return a 404. Once the configuration is set, this endpoint will indicate whether the server will share usage data with the Central team. If the server will share usage data, and contact information was provided, this endpoint will also return the provided work email address and organization name.

Request

This endpoint doesn't take any request parameter or data

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "key": "analytics",
  "setAt": "2018-01-06T00:32:52.787Z",
  "value": {
    "enabled": "true",
    "email": "my.email.address@getodk.org",
    "organization": "Organization Name"
  }
}

Schema

object key string The type of system configuration. Example: some_type setAt string ISO date format. The last time this system configuration was set. Example: 2018-01-06 00:32:52.787000+00:00 key None Example: analytics value object expand enabled boolean true if the server will share usage data with the Central team and false if not. Example: true email string The work email address to include with the metrics report. Example: my.email.address@getodk.org organization string The organization name to include with the metrics report. Example: Organization Name

HTTP Status: 404

Content Type: application/json

Example

{
  "code": 404.1,
  "message": "Could not find the resource you were looking for."
}

Schema

object code number Example: 404.1 message string Example: Could not find the resource you were looking for.

Setting new configuration for Usage Reporting

POST /v1/config/analytics

An Administrator can use this endpoint to choose whether the server will share anonymous usage data with the Central team. This configuration affects the entire server. Until the Usage Reporting configuration is set, Administrators will see a message on the Central administration website that provides further information.

If an Administrator specifies true for enabled, the server will share anonymous usage data monthly with the Central team. By specifying true, the Administrator accepts the Terms of Service and Privacy Policy. The Administrator can also share contact information to include with the report.

If an Administrator specifies false for enabled, the server will not share anonymous usage data with the Central team. Administrators will no longer see the message on the administration website.

If the Usage Reporting configuration is already set, the current configuration will be overwritten with the new one.

Request

Request body

Example

{
  "enabled": "true",
  "email": "my.email.address@getodk.org",
  "organization": "Organization Name"
}

Schema

object enabled boolean true if the server will share usage data with the Central team and false if not. Example: true email string The work email address to include with the metrics report. Example: my.email.address@getodk.org organization string The organization name to include with the metrics report. Example: Organization Name

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "key": "analytics",
  "setAt": "2018-01-06T00:32:52.787Z",
  "value": {
    "enabled": "true",
    "email": "my.email.address@getodk.org",
    "organization": "Organization Name"
  }
}

Schema

object key string The type of system configuration. Example: some_type setAt string ISO date format. The last time this system configuration was set. Example: 2018-01-06 00:32:52.787000+00:00 key None Example: analytics value object expand enabled boolean true if the server will share usage data with the Central team and false if not. Example: true email string The work email address to include with the metrics report. Example: my.email.address@getodk.org organization string The organization name to include with the metrics report. Example: Organization Name

Unsetting the current Usage Reporting configuration

DELETE /v1/config/analytics

If the Usage Reporting configuration is unset, Administrators will once again see a message on the Central administration website.

Request

This endpoint doesn't take any request parameter or data

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "success": true
}

Schema

object success boolean

Getting the title and description configured for the login page

GET /v1/config/login-appearance

(introduced: version 2026.1)

If no title or description has been configured for the login page, this endpoint will return a 404. Once a configuration is set, this endpoint will return the custom title and/or description that has been configured for the login page.

Request

This endpoint doesn't take any request parameter or data

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "key": "login-appearance",
  "setAt": "2018-01-06T00:32:52.787Z",
  "value": {
    "title": "Better Data, Better Cocoa",
    "description": "pencil"
  }
}

Schema

object key string The type of system configuration. Example: some_type setAt string ISO date format. The last time this system configuration was set. Example: 2018-01-06 00:32:52.787000+00:00 key None Example: login-appearance value object expand title string A custom title to show on the login page. Example: Better Data, Better Cocoa description string A custom description to show on the login page as a subtitle.

HTTP Status: 404

Content Type: application/json

Example

{
  "code": 404.1,
  "message": "Could not find the resource you were looking for."
}

Schema

object code number Example: 404.1 message string Example: Could not find the resource you were looking for.

Setting a new title and description for the login page

POST /v1/config/login-appearance

(introduced: version 2026.1)

An Administrator can use this endpoint to set a custom title and/or description to show to all users who visit the login page. The description will be shown as a subtitle. If a title or description is already set, the current configuration will be overwritten with the new one; the two configurations will not be merged.

Request

Request body

Example

{
  "title": "Better Data, Better Cocoa",
  "description": "pencil"
}

Schema

object title string A custom title to show on the login page. Example: Better Data, Better Cocoa description string A custom description to show on the login page as a subtitle.

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "key": "login-appearance",
  "setAt": "2018-01-06T00:32:52.787Z",
  "value": {
    "title": "Better Data, Better Cocoa",
    "description": "pencil"
  }
}

Schema

object key string The type of system configuration. Example: some_type setAt string ISO date format. The last time this system configuration was set. Example: 2018-01-06 00:32:52.787000+00:00 key None Example: login-appearance value object expand title string A custom title to show on the login page. Example: Better Data, Better Cocoa description string A custom description to show on the login page as a subtitle.

Unsetting the title and description configured for the login page

DELETE /v1/config/login-appearance

(introduced: version 2026.1)

If the configuration is unset, all users who visit the login page will once again see the default title and description.

Request

This endpoint doesn't take any request parameter or data

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "success": true
}

Schema

object success boolean

Getting the logo configured for the server

GET /v1/config/logo

(introduced: version 2026.1)

If no logo has been configured for the server, this endpoint will return a 404. Once a configuration is set, this endpoint will return the custom logo that has been configured.

Request

This endpoint doesn't take any request parameter or data

Response

HTTP Status: 200

Content Type: {the MIME type of the logo itself}

Example

"(binary data)"

Schema

HTTP Status: 404

Content Type: application/json

Example

{
  "code": 404.1,
  "message": "Could not find the resource you were looking for."
}

Schema

object code number Example: 404.1 message string Example: Could not find the resource you were looking for.

Setting a new logo for the server

POST /v1/config/logo

(introduced: version 2026.1)

An Administrator can use this endpoint to set a custom logo for the entire server. The logo will be shown to all users who visit the login page, as well as other pages, including the reset password page and set password page. If a logo is already set, the current logo will be overwritten with the new one.

Request

This endpoint doesn't take any request parameter or data

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "key": "logo",
  "setAt": "2018-01-06T00:32:52.787Z",
  "blobExists": "true"
}

Schema

object key string The type of system configuration. Example: some_type setAt string ISO date format. The last time this system configuration was set. Example: 2018-01-06 00:32:52.787000+00:00 blobExists boolean Whether a file has been set for this configuration. Example: true key None Example: logo

Unsetting the logo configured for the server

DELETE /v1/config/logo

(introduced: version 2026.1)

If the configuration is unset, all users who visit the login page (or another page that previously showed the custom logo) will once again see the default logo.

Request

This endpoint doesn't take any request parameter or data

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "success": true
}

Schema

object success boolean

Getting the hero image configured for the server

GET /v1/config/hero-image

(introduced: version 2026.1)

If no hero image has been configured for the server, this endpoint will return a 404. Once a configuration is set, this endpoint will return the custom hero image that has been configured.

Request

This endpoint doesn't take any request parameter or data

Response

HTTP Status: 200

Content Type: {the MIME type of the hero image itself}

Example

"(binary data)"

Schema

HTTP Status: 404

Content Type: application/json

Example

{
  "code": 404.1,
  "message": "Could not find the resource you were looking for."
}

Schema

object code number Example: 404.1 message string Example: Could not find the resource you were looking for.

Setting a new hero image for the server

POST /v1/config/hero-image

(introduced: version 2026.1)

An Administrator can use this endpoint to set a custom hero image for the entire server. The hero image will be shown to all users who visit the login page, as well as other pages, including the reset password page and set password page. If a hero image is already set, the current image will be overwritten with the new one.

Request

This endpoint doesn't take any request parameter or data

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "key": "hero-image",
  "setAt": "2018-01-06T00:32:52.787Z",
  "blobExists": "true"
}

Schema

object key string The type of system configuration. Example: some_type setAt string ISO date format. The last time this system configuration was set. Example: 2018-01-06 00:32:52.787000+00:00 blobExists boolean Whether a file has been set for this configuration. Example: true key None Example: hero-image

Unsetting the hero image configured for the server

DELETE /v1/config/hero-image

(introduced: version 2026.1)

If the configuration is unset, users who visit the login page (or another page that previously showed the custom hero image) will no longer see the custom image. Instead, they will see either a default image or no image at all.

Request

This endpoint doesn't take any request parameter or data

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "success": true
}

Schema

object success boolean

Getting all public configuration

GET /v1/config/public

(introduced: version 2026.1)

This endpoint will return all server configuration that is publicly accessible in a single object. This endpoint does not require authentication.

The following configurations are publicly accessible:

• login-appearance
• logo
• hero-image

The following configuration is not publicly accessible and requires authentication to access:

• analytics

For configuration that stores binary data (e.g., logo), this endpoint only returns metadata about the configuration (e.g., when the configuration was last set). To retrieve the binary data, you can use the corresponding endpoint described above (e.g., /v1/config/logo). If the configuration is publicly accessible, you can access the binary data without providing authentication via /v1/config/public/:key (e.g., /v1/config/public/logo).

Request

This endpoint doesn't take any request parameter or data

Response

HTTP Status: 200

Content Type: application/json

Example

{
  "login-appearance": {
    "key": "login-appearance",
    "setAt": "2018-01-06T00:32:52.787Z",
    "value": {
      "title": "Better Data, Better Cocoa",
      "description": "pencil"
    }
  },
  "logo": {
    "key": "logo",
    "setAt": "2018-01-06T00:32:52.787Z",
    "blobExists": "true"
  },
  "hero-image": {
    "key": "hero-image",
    "setAt": "2018-01-06T00:32:52.787Z",
    "blobExists": "true"
  }
}

Schema

object login-appearance object expand key string The type of system configuration. Example: some_type setAt string ISO date format. The last time this system configuration was set. Example: 2018-01-06 00:32:52.787000+00:00 key None Example: login-appearance value object expand title string A custom title to show on the login page. Example: Better Data, Better Cocoa description string A custom description to show on the login page as a subtitle. logo object expand key string The type of system configuration. Example: some_type setAt string ISO date format. The last time this system configuration was set. Example: 2018-01-06 00:32:52.787000+00:00 blobExists boolean Whether a file has been set for this configuration. Example: true key None Example: logo hero-image object expand key string The type of system configuration. Example: some_type setAt string ISO date format. The last time this system configuration was set. Example: 2018-01-06 00:32:52.787000+00:00 blobExists boolean Whether a file has been set for this configuration. Example: true key None Example: hero-image

Usage Report Preview

(introduced: version 1.3)

An Administrator of Central may opt in to sending periodic reports summarizing usage. Configuration of this reporting is described here. For added transparency, the API provides a preview of the reported metrics.

Getting the Usage Report preview

GET /v1/analytics/preview

An Administrator can use this endpoint to preview the metrics being sent. The preview is computed on the fly and represents what the report would look like if sent at that time. This endpoint does not directly submit the Usage Report; that is handled internally as a scheduled Central task.

Request

This endpoint doesn't take any request parameter or data

Response

HTTP Status: 200

Content Type: application/json

Example

{}

Schema

object

Server Audit Logs

(introduced: version 0.6)

Many actions on ODK Central will automatically log an event to the Server Audit Log. Creating a new Form, for instance, will log a form.create event, with information about the Actor who performed the action, and sometimes some additional details specific to the event.

Any time an audit action is logged, the request headers are checked. If X-Action-Notes are provided anywhere, those notes will be logged into the audit entries as well. Note that some requests generate multiple audit entries; in these cases, the note will be attached to every entry logged.

Server Audit Logs entries are created for the following actions:

• user.create when a new User is created.
• user.update when User information is updated, like email or password.
• user.assignment.create when a User is assigned to a Server Role.
• user.assignment.delete when a User is unassigned from a Server Role.
• user.preference.update when a site-wide or project-specific User preference is set or updated.
• user.preference.delete when a site-wide or project-specific User preference is removed.
• user.session.create when a User logs in.
• user.delete when a User is deleted.
• project.create when a new Project is created.
• project.update when top-level Project information is updated, like its name.
• project.delete when a Project is deleted.
• form.create when a new Form is created.
• form.update when top-level Form information is updated, like its name or state.
• form.update.draft.set when a Draft Form definition is set.
• form.update.draft.delete when a Draft Form definition is deleted.
• form.update.publish when a Draft Form is published to the Form.
• form.update.draft.replace when a Draft Form is changed in place.
• form.attachment.update when a Form Attachment binary is set or cleared.
• form.submissions.export when a Form's Submissions are exported to CSV.
• form.delete when a Form is deleted.
• form.restore when a Form that was deleted is restored.
• form.purge when a Form is permanently purged.
• field_key.create when a new App User is created.
• field_key.assignment.create when an App User is assigned to a Server Role.
• field_key.assignment.delete when an App User is unassigned from a Server Role.
• field_key.session.end when an App User's access is revoked.
• field_key.delete when an App User is deleted.
• public_link.create when a new Public Link is created.
• public_link.assignment.create when a Public Link is assigned to a Server Role.
• public_link.assignment.delete when a Public Link is unassigned from a Server Role.
• public_link.session.end when a Public Link's access is revoked.
• public_link.delete when a Public Link is deleted.
• submission.create when a new Submission is created.
• submission.update when a Submission's metadata is updated.
• submission.update.version when a Submission XML data is updated.
• submission.attachment.update when a Submission Attachment binary is set or cleared.
• submission.delete when a Submission is soft-deleted.
• submission.purge when soft-deleted Submissions are purged.
• submission.restore when a Submission is restored.
• submission.backlog.hold when an Entity Submission is first held in processing backlog.
• submission.backlog.reprocess when an Entity Submission is reprocessed and removed from the backlog.
• submission.backlog.force when an Entity Submission is force-processed after being in backlog.
• dataset.create when a Dataset is created.
• dataset.update when a Dataset is updated.
• dataset.update.publish when a Dataset is published.
• dataset.delete when a Dataset is deleted.
• dataset.update.property.delete when a Dataset Property is deleted.
• entity.create when an Entity is created.
• entity.error when there is an error processing a Submission to create or update an Entity.
• entity.update.version when an Entity is updated.
• entity.update.resolve when an Entity conflict is resolved.
• entity.delete when an Entity is deleted.
• entity.restore when a deleted Entity is restored.
• entity.purge when a deleted Entity is purged (ppermanently deleted).
• entity.bulk.delete when Entities are deleted in bulk.
• entity.bulk.restore when Entities are restored in bulk.
• config.set when a system configuration is set.
• upgrade.server when Central is upgraded to a new version.
• upgrade.process.form.entities_version when Central flags an Entity-related Form for a potential automatic upgrade.
• analytics when a Usage Report is attempted.
• blobs.s3.upload when blobs are moved from the database to external storage.
• blobs.s3.failed-to-pending when blobs that failed to upload are reset to the pending state to be retried.
• Deprecated: backup when a backup operation is attempted for Google Drive backups.

Getting Audit Log Entries

GET /v1/audits

This resource allows access to those log entries, with some paging and filtering options. These are provided by querystring parameters: action allows filtering by the action types listed above, start and end allow filtering by log timestamp (see below), and limit and offset control paging. If no paging parameters are given, the server will attempt to return every audit log entry that it has.

The start and end parameters work based on exact timestamps, given in ISO 8601 format. It is possible to provide just a datestring (eg 2000-01-01), in which case midnight will be inferred. But this value alone leaves the timezone unspecified. When no timezone is given, the server's local time will be used: the standard Docker deployment will always set server local time to UTC, but installations may have been customized, and there is no guarantee the UTC default hasn't been overridden.

For this reason, we recommend always setting a timezone when querying based on start and end: either by appending a z to indicate UTC (eg 2000-01-01z) or by explicitly specifying a timezone per ISO 8601 (eg 2000-01-01+08). The same applies for full timestamps (eg 2000-01-01T12:12:12z, 2000-01-01T12:12:12+08).

start may be given without end, and vice versa, in which case the timestamp filter will only be bounded on the specified side. They are both inclusive (>= and <=, respectively).

This endpoint supports retrieving extended metadata; provide a header X-Extended-Metadata: true to additionally expand the actorId into full actor details, and acteeId into full actee details. The actor will always be an Actor, but the actee may be an Actor, a Project, a Form, or some other type of object depending on the type of action.

Request

Parameters

action (query)	string The name of the action to filter by. Example: form.create
start (query)	string The timestamp before which log entries are to be filtered out. Example: 2000-01-01z
end (query)	string The timestamp after which log entries are to be filtered out. Example: 2000-12-31T23:59.999z
limit (query)	number The maximum number of entries to return. Example: 100
offset (query)	number The zero-indexed number of entries to skip from the result. Example: 200

Response

HTTP Status: 200

Content Type: application/json

Example

[
  {
    "actorId": 42,
    "action": "user.session.create",
    "details": {
      "userAgent": "Mozilla/5.0"
    },
    "acteeId": "85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "loggedAt": "2018-04-18T23:19:14.802Z"
  }
]

Schema

array actorId number The ID of the actor, if any, that initiated the action. Example: 42 action string The action that was taken. Example: form.create acteeId string The ID of the permissioning object against which the action was taken. Example: 85cb9aff-005e-4edd-9739-dc9c1a829c44 details object Additional details about the action that vary according to the type of action. loggedAt string ISO date format Example: 2018-04-18T23:19:14.802Z

HTTP Status: 200

Content Type: application/json; extended

Example

[
  {
    "actorId": 42,
    "action": "form.create",
    "details": {
      "userAgent": "Mozilla/5.0"
    },
    "acteeId": "85cb9aff-005e-4edd-9739-dc9c1a829c44",
    "loggedAt": "2018-04-18T23:19:14.802Z",
    "actor": {
      "createdAt": "2018-04-18T23:19:14.802Z",
      "displayName": "My Display Name",
      "id": 115,
      "type": "user",
      "updatedAt": "2018-04-18T23:42:11.406Z",
      "deletedAt": "2018-04-18T23:42:11.406Z"
    }
  }
]

Schema

array actorId number The ID of the actor, if any, that initiated the action. Example: 42 action string The action that was taken. Example: form.create acteeId string The ID of the permissioning object against which the action was taken. Example: 85cb9aff-005e-4edd-9739-dc9c1a829c44 details object Additional details about the action that vary according to the type of action. loggedAt string ISO date format Example: 2018-04-18T23:19:14.802Z actor object expand createdAt string ISO date format Example: 2018-04-18 23:19:14.802000+00:00 displayName string All Actors, regardless of type, have a display name Example: My Display Name id number Example: 115.0 type enum The type of actor expand user string field_key string public_link string singleUse string updatedAt string ISO date format Example: 2018-04-18 23:42:11.406000+00:00 deletedAt string ISO date format Example: 2018-04-18 23:42:11.406000+00:00 actee object The details of the actee given by acteeId. Depending on the action type, this could be a number of object types, including an Actor, a Project, or a Form.

HTTP Status: 400

Content Type: application/json

Example

{
  "code": "400",
  "message": "Could not parse the given data (2 chars) as json."
}

Schema

object code number Example: 400 details object a subobject that contains programmatically readable details about this error message string Example: Could not parse the given data (2 chars) as json.

Direct Backup

(introduced: version 1.1)

ODK Central offers an HTTP endpoint that will immediately perform a backup on the system database and send that encrypted backup as the response. To use it, POST with an encryption passphrase.

Note that performing the backup takes a great deal of time, during which the request will be held open. As a result, the endpoint will trickle junk data every five seconds while that processing is occurring to prevent the request from timing out. Depending on how much data you have, it can take many minutes for the data stream to speed up to a full transfer rate.

Using an Encryption Passphrase

POST /v1/backup

Use the POST verb to start a direct download ad-hoc backup. You will want to supply a passphrase with your chosen encryption passphrase. It is possible to omit this, in which case the backup will still be encrypted, but it will decrypt given an empty passphrase.

Please see the section notes above about the long-running nature of this endpoint.

Request

Request body

Example

{
  "passphrase": "my-password"
}

Schema

object passphrase string The passphrase with which to encrypt the backup.

Response

HTTP Status: 200

Content Type: application/zip

Example

"(binary data)"

Schema

string

Did this page help you?

Selecting an option will open a 1-question survey

👍 Yes 👎 No