Skip to content

Commit 81e8069

Browse files
ktuitektuite
committed
Refine API docs
1 parent ad2edd3 commit 81e8069

1 file changed

Lines changed: 43 additions & 20 deletions

File tree

‎docs/api.yaml‎

Lines changed: 43 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -44,17 +44,20 @@ info:
4444
## ODK Central v2026.2
4545

4646
**Added**:
47-
- Actor properties allow you to attach custom key/value metadata to App Users and Public Links within a project. This can be used to tag users with attributes like region or supervisor.
47+
- [Actor Properties](/central-api-accounts-and-users/#actor-properties) allow you to attach custom key/value metadata to App Users and Public Links within a project. This can be used to tag users with attributes like region or supervisor.
4848
- [POST /projects/:id/actor-properties](/central-api-accounts-and-users/#registering-an-actor-property-name) to register a new property name for a project.
4949
- [GET /projects/:id/actor-properties](/central-api-accounts-and-users/#listing-actor-property-names) to list property names. Use `X-Extended-Metadata: true` to also retrieve the distinct values currently in use.
50-
- [GET /projects/:id/app-users/:id](/central-api-accounts-and-users/#getting-app-user-details) to get a single App User. Use `X-Extended-Metadata: true` to include property values.
5150
- [PATCH /projects/:id/app-users/:id](/central-api-accounts-and-users/#setting-actor-property-values-on-an-app-user) to set or unset property values on an App User.
52-
- [GET /projects/:id/forms/:xmlFormId/public-links/:id](/central-api-form-management/#getting-link-details) to get a single Public Link. Use `X-Extended-Metadata: true` to include property values.
5351
- [PATCH /projects/:id/forms/:xmlFormId/public-links/:id](/central-api-form-management/#setting-actor-property-values-on-a-link) to set or unset property values on a Public Link.
54-
- New audit log events: `actor.property.create`, `field_key.property.set`, and `public_link.property.set`.
55-
52+
- New audit log events: `actor_property.create`, `field_key.property.set`, and `public_link.property.set`.
53+
5654
**Changed**:
5755
- The [Getting Form Details](/central-api-form-management/#getting-form-details), [Listing Published Form Versions](/central-api-form-management/#listing-published-form-versions) and [Getting Form Version Details](/central-api-form-management/#getting-form-version-details) endpoints now return a `publishNotes` field in extended metadata.
56+
- Several existing endpoints now support [Actor Properties](/central-api-accounts-and-users/#actor-properties):
57+
- [GET /projects/:id/app-users](/central-api-accounts-and-users/#listing-all-app-users) and [GET /projects/:id/app-users/:id](/central-api-accounts-and-users/#getting-app-user-details) now return a `properties` object in extended metadata.
58+
- [POST /projects/:id/app-users](/central-api-accounts-and-users/#creating-a-new-app-user) now accepts an optional `properties` object to set property values at creation time.
59+
- [GET /projects/:id/forms/:xmlFormId/public-links](/central-api-form-management/#listing-all-links) and [GET /projects/:id/forms/:xmlFormId/public-links/:id](/central-api-form-management/#getting-link-details) now return a `properties` object in extended metadata.
60+
- [POST /projects/:id/forms/:xmlFormId/public-links](/central-api-form-management/#creating-a-link) now accepts an optional `properties` object to set property values at creation time.
5861

5962
## ODK Central v2026.1
6063

@@ -973,7 +976,7 @@ tags:
973976
* `public_link.session.end` when a Public Link's access is revoked.
974977
* `public_link.delete` when a Public Link is deleted.
975978
* `public_link.property.set` when actor property values are set on a Public Link.
976-
* `actor.property.create` when a new actor property name is registered for a project.
979+
* `actor_property.create` when a new actor property name is registered for a project.
977980
* `submission.create` when a new Submission is created.
978981
* `submission.update` when a Submission's metadata is updated.
979982
* `submission.update.version` when a Submission XML data is updated.
@@ -1916,7 +1919,7 @@ paths:
19161919
description: |-
19171920
Currently, there are no paging or filtering options, so listing `App User`s will get you every App User in the system, every time.
19181921

1919-
This endpoint supports retrieving extended metadata; provide a header `X-Extended-Metadata: true` to additionally retrieve the `lastUsed` timestamp of each App User, as well as to retrieve the details of the `Actor` the App User was `createdBy`.
1922+
This endpoint supports retrieving extended metadata; Provide a header `X-Extended-Metadata: true` to additionally retrieve the `lastUsed` timestamp of each App User, the details of the `Actor` the App User was `createdBy`, and a `properties` object containing any actor property values set on the App User.
19201923
operationId: listAllAppUsers
19211924
parameters:
19221925
- name: projectId
@@ -1945,7 +1948,6 @@ paths:
19451948
deletedAt: 2018-04-18T23:42:11.406Z
19461949
token: d1!E2GVHgpr4h9bpxxtqUJ7EVJ1Q$Dusm2RBXg8XyVJMCBCbvyE8cGacxUx3bcUT
19471950
projectId: 1
1948-
lastUsed: 2018-04-14T08:34:21.633Z
19491951
application/json; extended:
19501952
schema:
19511953
type: array
@@ -1969,6 +1971,8 @@ paths:
19691971
updatedAt: 2018-04-18T23:42:11.406Z
19701972
deletedAt: 2018-04-18T23:42:11.406Z
19711973
lastUsed: 2018-04-14T08:34:21.633Z
1974+
properties:
1975+
region: North
19721976
post:
19731977
tags:
19741978
- App Users
@@ -1977,6 +1981,8 @@ paths:
19771981
The only information required to create a new `App User` is its `displayName` (this is called "Nickname" in the administrative panel).
19781982

19791983
When an App User is created, they are assigned no rights. They will be able to authenticate and list forms on a mobile client, but the form list will be empty, as the list only includes Forms that the App User has read access to. Once an App User is created, you'll likely wish to use the [Form Assignments resource](/central-api-form-management/#form-assignments) to actually assign the `app-user` role to them for the Forms you wish.
1984+
1985+
You may also optionally provide a `properties` object to set pre-registered [Actor Property](/central-api-accounts-and-users/#actor-properties) values on the App User at creation time.
19801986
operationId: createAppUser
19811987
parameters:
19821988
- name: projectId
@@ -1997,8 +2003,16 @@ paths:
19972003
displayName:
19982004
type: string
19992005
description: The friendly nickname of the `App User` to be created.
2006+
properties:
2007+
type: object
2008+
description: An optional object mapping pre-registered [Actor Property](/central-api-accounts-and-users/#actor-properties) names to string values.
2009+
additionalProperties:
2010+
type: string
2011+
nullable: true
20002012
example:
20012013
displayName: My Display Name
2014+
properties:
2015+
region: North
20022016
required: false
20032017
responses:
20042018
"200":
@@ -2117,11 +2131,11 @@ paths:
21172131
- App Users
21182132
summary: Setting Actor Property Values on an App User
21192133
description: |-
2120-
Sets or unsets actor property values on an App User. The body must contain a `properties` object mapping property names to string values or `null`. Sending `null` for a property unsets it. Property names must have been registered on the project via `POST /v1/projects/{projectId}/actor-properties` before they can be set.
2134+
Sets or unsets pre-registered [Actor Property](/central-api-accounts-and-users/#actor-properties) values on an App User. The body must contain a `properties` object mapping property names to string values or `null`. Sending `null` for a property unsets it.
21212135

21222136
Returns the extended App User, including a `properties` object containing all currently set property values.
21232137

2124-
Requires `project.update` permission.
2138+
Requires `field_key.update` permission.
21252139
operationId: patchAppUser
21262140
parameters:
21272141
- name: id
@@ -2244,7 +2258,7 @@ paths:
22442258

22452259
Property names follow the same rules as Entity property names: they must be non-empty, may contain letters, digits, hyphens, and underscores, and the name `displayName` (case-insensitive) is reserved.
22462260

2247-
Requires `project.update` permission.
2261+
Requires `actor_property.update` permission.
22482262
operationId: createActorProperty
22492263
parameters:
22502264
- name: projectId
@@ -5369,7 +5383,7 @@ paths:
53695383
description: |-
53705384
This will list every Public Access Link upon this Form.
53715385

5372-
This endpoint supports retrieving extended metadata; provide a header `X-Extended-Metadata: true` to retrieve the Actor the Link was `createdBy`.
5386+
This endpoint supports retrieving extended metadata; Provide a header `X-Extended-Metadata: true` to additionally retrieve the Actor the Link was `createdBy` and a `properties` object containing any actor property values set on the Link.
53735387
operationId: listAllLinks
53745388
parameters:
53755389
- name: projectId
@@ -5426,17 +5440,16 @@ paths:
54265440
type: user
54275441
updatedAt: 2018-04-18T23:42:11.406Z
54285442
deletedAt: 2018-04-18T23:42:11.406Z
5443+
properties:
5444+
region: North
54295445
post:
54305446
tags:
54315447
- Public Access Links
54325448
summary: Creating a Link
5433-
description: 'To create a new Public Access Link to this Form, you must send
5434-
at least a `displayName` for the resulting Actor. You may also provide `once:
5435-
true` if you want to create a link that [can only be filled by each respondent
5436-
once](https://blog.enketo.org/single-submission-surveys/). This setting is
5437-
enforced by Enketo using local device tracking; the link is still distributable
5438-
to multiple recipients, and the enforcement can be defeated by using multiple
5439-
browsers or devices.'
5449+
description: |-
5450+
To create a new Public Access Link to this Form, you must send at least a `displayName` for the resulting Actor. You may also provide `once: true` if you want to create a link that [can only be filled by each respondent once](https://blog.enketo.org/single-submission-surveys/). This setting is enforced by Enketo using local device tracking; the link is still distributable to multiple recipients, and the enforcement can be defeated by using multiple browsers or devices.
5451+
5452+
You may also optionally provide a `properties` object to set pre-registered [Actor Property](/central-api-accounts-and-users/#actor-properties) values on the Link at creation time.
54405453
operationId: createLink
54415454
parameters:
54425455
- name: projectId
@@ -5471,9 +5484,17 @@ paths:
54715484
description: If set to `true`, an Enketo [single submission survey](https://blog.enketo.org/single-submission-surveys/)
54725485
will be created instead of a standard one, limiting respondents
54735486
to a single submission each.
5487+
properties:
5488+
type: object
5489+
description: An optional object mapping pre-registered [Actor Property](/central-api-accounts-and-users/#actor-properties) names to string values.
5490+
additionalProperties:
5491+
type: string
5492+
nullable: true
54745493
example:
54755494
displayName: my public link
54765495
once: false
5496+
properties:
5497+
region: North
54775498
required: false
54785499
responses:
54795500
"200":
@@ -5578,9 +5599,11 @@ paths:
55785599
- Public Access Links
55795600
summary: Setting Actor Property Values on a Link
55805601
description: |-
5581-
Sets or unsets actor property values on a Public Access Link. The body must contain a `properties` object mapping property names to string values or `null`. Sending `null` for a property unsets it. Property names must have been registered on the project via `POST /v1/projects/{projectId}/actor-properties` before they can be set.
5602+
Sets or unsets pre-registered [Actor Property](/central-api-accounts-and-users/#actor-properties) values on a Public Access Link. The body must contain a `properties` object mapping property names to string values or `null`. Sending `null` for a property unsets it.
55825603

55835604
Returns the extended Public Link, including a `properties` object containing all currently set property values.
5605+
5606+
Requires `public_link.update` permission.
55845607
operationId: patchLink
55855608
parameters:
55865609
- name: projectId

0 commit comments

Comments
 (0)