{
  "openapi": "3.1.0",
  "info": {
    "title": "DatumForms project API",
    "version": "2026-11-15",
    "description": "GET and POST operations share /api/developer-api. Each operation contract and permission is enumerated in x-datumforms-operations."
  },
  "servers": [
    {
      "url": "https://app.datumforms.com/api"
    }
  ],
  "security": [
    {
      "ProjectKey": []
    }
  ],
  "paths": {
    "/developer-api": {
      "get": {
        "operationId": "readProjectOperation",
        "parameters": [
          {
            "name": "operation",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "account.get",
                "groups.list",
                "surveys.get",
                "surveys.review",
                "resources.get",
                "responses.list",
                "collection.get",
                "aliases.get",
                "members.list",
                "sheets.status",
                "keys.lookup_groups"
              ]
            }
          },
          {
            "name": "group_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "form_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "response_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "resource_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "alias",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "after_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "filters",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_collection_details",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "include_location",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "after_operation",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Allowance or plan requirement",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Wrong method",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict or stale state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "writeProjectOperation",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "groups.set_availability"
                      },
                      "idempotency_key": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9:_-]{8,100}$"
                      },
                      "group_id": {
                        "type": "integer",
                        "description": "Group ID returned by groups.list or groups.save."
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "active": {
                            "type": "boolean",
                            "description": "true opens collection; false closes it."
                          }
                        },
                        "required": [
                          "active"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "required": [
                      "operation",
                      "idempotency_key",
                      "group_id",
                      "data"
                    ],
                    "additionalProperties": false,
                    "title": "groups.set_availability"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "groups.save"
                      },
                      "idempotency_key": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9:_-]{8,100}$"
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string",
                            "description": "Group name, 1\u2013256 characters."
                          },
                          "group_id": {
                            "type": "integer",
                            "description": "Existing group ID when editing."
                          },
                          "categories": {
                            "type": "string",
                            "description": "Description."
                          }
                        },
                        "required": [
                          "name"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "required": [
                      "operation",
                      "idempotency_key",
                      "data"
                    ],
                    "additionalProperties": false,
                    "title": "groups.save"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "groups.assign_form"
                      },
                      "idempotency_key": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9:_-]{8,100}$"
                      },
                      "group_id": {
                        "type": "integer",
                        "description": "Destination group ID."
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "form_id": {
                            "type": "integer",
                            "description": "Saved page ID returned by surveys.save."
                          }
                        },
                        "required": [
                          "form_id"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "required": [
                      "operation",
                      "idempotency_key",
                      "group_id",
                      "data"
                    ],
                    "additionalProperties": false,
                    "title": "groups.assign_form"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "surveys.save"
                      },
                      "idempotency_key": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9:_-]{8,100}$"
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string",
                            "description": "Page name."
                          },
                          "elements": {
                            "type": "array",
                            "description": "Canonical Form Studio element definitions. Each new field needs a type, client_id, caption and type-specific settings."
                          },
                          "form_id": {
                            "type": "integer",
                            "description": "Existing page ID when editing."
                          },
                          "expected_edit_hash": {
                            "type": "string",
                            "description": "Required when editing; from surveys.get."
                          },
                          "page_number": {
                            "type": "integer",
                            "description": "Positive page order."
                          },
                          "purpose": {
                            "type": "string",
                            "description": "Page purpose supported by Form Studio."
                          },
                          "allow_uploads": {
                            "type": "boolean",
                            "description": "Whether the page permits attachments."
                          },
                          "page_logic": {
                            "type": "object",
                            "description": "Page conditions."
                          },
                          "branching": {
                            "type": "object",
                            "description": "Forward branching configuration."
                          }
                        },
                        "required": [
                          "name",
                          "elements"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "required": [
                      "operation",
                      "idempotency_key",
                      "data"
                    ],
                    "additionalProperties": false,
                    "title": "surveys.save"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "surveys.publish"
                      },
                      "idempotency_key": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9:_-]{8,100}$"
                      },
                      "group_id": {
                        "type": "integer",
                        "description": "Reviewed survey group."
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "review_token": {
                            "type": "string",
                            "description": "Fresh fingerprint returned by surveys.review."
                          }
                        },
                        "required": [
                          "review_token"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "required": [
                      "operation",
                      "idempotency_key",
                      "group_id",
                      "data"
                    ],
                    "additionalProperties": false,
                    "title": "surveys.publish"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "assignments.save"
                      },
                      "idempotency_key": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9:_-]{8,100}$"
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "email": {
                            "type": "string",
                            "description": "Existing participant account email."
                          },
                          "groups_id": {
                            "type": "integer",
                            "description": "Survey group to assign. Does not edit an existing membership."
                          }
                        },
                        "required": [
                          "email",
                          "groups_id"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "required": [
                      "operation",
                      "idempotency_key",
                      "data"
                    ],
                    "additionalProperties": false,
                    "title": "assignments.save"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "resources.save"
                      },
                      "idempotency_key": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9:_-]{8,100}$"
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "code_title": {
                            "type": "string",
                            "description": "Resource title."
                          },
                          "js_css": {
                            "type": "string",
                            "description": "Resource language: javascript or css."
                          },
                          "resource_type": {
                            "type": "string",
                            "description": "Resource representation: code or link."
                          },
                          "resource_value": {
                            "type": "string",
                            "description": "JavaScript or CSS source."
                          },
                          "id": {
                            "type": "integer",
                            "description": "Existing resource ID when editing."
                          }
                        },
                        "required": [
                          "code_title",
                          "js_css",
                          "resource_type",
                          "resource_value"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "required": [
                      "operation",
                      "idempotency_key",
                      "data"
                    ],
                    "additionalProperties": false,
                    "title": "resources.save"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "resources.delete"
                      },
                      "idempotency_key": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9:_-]{8,100}$"
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "integer",
                            "description": "Resource ID from resources.get."
                          }
                        },
                        "required": [
                          "id"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "required": [
                      "operation",
                      "idempotency_key",
                      "data"
                    ],
                    "additionalProperties": false,
                    "title": "resources.delete"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "responses.create"
                      },
                      "idempotency_key": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9:_-]{8,100}$"
                      },
                      "group_id": {
                        "type": "integer",
                        "description": "Published ordinary collection."
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "reason": {
                            "type": "string",
                            "description": "Nonblank audit reason, up to 1000 characters."
                          },
                          "answers": {
                            "type": "array",
                            "description": "1\u20132000 answer cells with questionRef, value and optional row/col."
                          },
                          "display_name": {
                            "type": "string",
                            "description": "Optional display name, up to 255 characters."
                          }
                        },
                        "required": [
                          "reason",
                          "answers"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "required": [
                      "operation",
                      "idempotency_key",
                      "group_id",
                      "data"
                    ],
                    "additionalProperties": false,
                    "title": "responses.create"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "responses.update"
                      },
                      "idempotency_key": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9:_-]{8,100}$"
                      },
                      "response_id": {
                        "type": "integer",
                        "description": "ID from responses.list."
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "expected_revision": {
                            "type": "integer",
                            "description": "Current response revision from responses.list."
                          },
                          "reason": {
                            "type": "string",
                            "description": "Nonblank reason, up to 1000 characters."
                          },
                          "answers": {
                            "type": "array",
                            "description": "Answer cells in the original version; null clears a cell."
                          }
                        },
                        "required": [
                          "expected_revision",
                          "reason",
                          "answers"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "required": [
                      "operation",
                      "idempotency_key",
                      "response_id",
                      "data"
                    ],
                    "additionalProperties": false,
                    "title": "responses.update"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "responses.delete"
                      },
                      "idempotency_key": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9:_-]{8,100}$"
                      },
                      "response_id": {
                        "type": "integer",
                        "description": "Ordinary response ID."
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "expected_revision": {
                            "type": "integer",
                            "description": "Current response revision."
                          },
                          "reason": {
                            "type": "string",
                            "description": "Nonblank reason, up to 1000 characters."
                          }
                        },
                        "required": [
                          "expected_revision",
                          "reason"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "required": [
                      "operation",
                      "idempotency_key",
                      "response_id",
                      "data"
                    ],
                    "additionalProperties": false,
                    "title": "responses.delete"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "location.correct"
                      },
                      "idempotency_key": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9:_-]{8,100}$"
                      },
                      "response_id": {
                        "type": "integer",
                        "description": "Ordinary response ID."
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "expected_revision": {
                            "type": "integer",
                            "description": "Current response revision."
                          },
                          "latitude": {
                            "type": "number",
                            "description": "Latitude from -90 to 90."
                          },
                          "longitude": {
                            "type": "number",
                            "description": "Longitude from -180 to 180."
                          },
                          "reason": {
                            "type": "string",
                            "description": "Correction reason, up to 1000 characters."
                          }
                        },
                        "required": [
                          "expected_revision",
                          "latitude",
                          "longitude",
                          "reason"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "required": [
                      "operation",
                      "idempotency_key",
                      "response_id",
                      "data"
                    ],
                    "additionalProperties": false,
                    "title": "location.correct"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "monthly.create"
                      },
                      "idempotency_key": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9:_-]{8,100}$"
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "source_group_id": {
                            "type": "integer",
                            "description": "Published source group from groups.list."
                          },
                          "expected_source_version_id": {
                            "type": "integer",
                            "description": "Its current published_version_id."
                          },
                          "name": {
                            "type": "string",
                            "description": "New group name."
                          }
                        },
                        "required": [
                          "source_group_id",
                          "expected_source_version_id",
                          "name"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "required": [
                      "operation",
                      "idempotency_key",
                      "data"
                    ],
                    "additionalProperties": false,
                    "title": "monthly.create"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "aliases.set"
                      },
                      "idempotency_key": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9:_-]{8,100}$"
                      },
                      "group_id": {
                        "type": "integer",
                        "description": "Published destination group."
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "alias": {
                            "type": "string",
                            "description": "Stable reference name: lowercase first letter and up to 63 lowercase letters, digits, hyphens or underscores."
                          },
                          "expected_revision": {
                            "type": "integer",
                            "description": "Revision from aliases.get; 0 for a new reference."
                          }
                        },
                        "required": [
                          "alias",
                          "expected_revision"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "required": [
                      "operation",
                      "idempotency_key",
                      "group_id",
                      "data"
                    ],
                    "additionalProperties": false,
                    "title": "aliases.set"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "lookups.save"
                      },
                      "idempotency_key": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9:_-]{8,100}$"
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string",
                            "description": "Lowercase-leading lookup name, up to 64 characters."
                          },
                          "collection_aliases": {
                            "type": "array",
                            "description": "1\u201320 existing alias names."
                          },
                          "question_refs": {
                            "type": "array",
                            "description": "1\u2013500 positive question IDs."
                          },
                          "active": {
                            "type": "boolean",
                            "description": "false disables the lookup; defaults true."
                          }
                        },
                        "required": [
                          "name",
                          "collection_aliases",
                          "question_refs"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "required": [
                      "operation",
                      "idempotency_key",
                      "data"
                    ],
                    "additionalProperties": false,
                    "title": "lookups.save"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "sheets.refresh"
                      },
                      "idempotency_key": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9:_-]{8,100}$"
                      },
                      "group_id": {
                        "type": "integer",
                        "description": "Group whose existing Sheets connection to refresh."
                      },
                      "data": {
                        "type": "object",
                        "properties": {},
                        "required": [],
                        "additionalProperties": true
                      }
                    },
                    "required": [
                      "operation",
                      "idempotency_key",
                      "group_id",
                      "data"
                    ],
                    "additionalProperties": false,
                    "title": "sheets.refresh"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "keys.update_lookup_groups"
                      },
                      "idempotency_key": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9:_-]{8,100}$"
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "key_id": {
                            "type": "integer",
                            "description": "Read-only key ID from keys.lookup_groups."
                          },
                          "collection_ids": {
                            "type": "array",
                            "description": "1\u2013500 permitted group IDs."
                          },
                          "expected_collection_ids": {
                            "type": "array",
                            "description": "Exact current array from keys.lookup_groups."
                          }
                        },
                        "required": [
                          "key_id",
                          "collection_ids",
                          "expected_collection_ids"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "required": [
                      "operation",
                      "idempotency_key",
                      "data"
                    ],
                    "additionalProperties": false,
                    "title": "keys.update_lookup_groups"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "recruitment.stop"
                      },
                      "idempotency_key": {
                        "type": "string",
                        "pattern": "^[A-Za-z0-9:_-]{8,100}$"
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "study_id": {
                            "type": "string",
                            "description": "Study UUID from the recruitment study result."
                          }
                        },
                        "required": [
                          "study_id"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "required": [
                      "operation",
                      "idempotency_key",
                      "data"
                    ],
                    "additionalProperties": false,
                    "title": "recruitment.stop"
                  }
                ],
                "discriminator": {
                  "propertyName": "operation"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Allowance or plan requirement",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Resource unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Wrong method",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict or stale state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/csv-import": {
      "get": {
        "operationId": "readSupplementaryImportStatus",
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": true,
            "schema": {
              "const": "status"
            }
          },
          {
            "name": "upload_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful action",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Project access required"
          },
          "409": {
            "description": "Changed state or unavailable operation"
          }
        }
      },
      "post": {
        "operationId": "writeSupplementaryImportAction",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "required": [
                      "action",
                      "project_id",
                      "group_id",
                      "name",
                      "bytes",
                      "sha256",
                      "request_id",
                      "options"
                    ],
                    "properties": {
                      "action": {
                        "const": "prepare"
                      },
                      "project_id": {
                        "type": "integer"
                      },
                      "group_id": {
                        "type": "integer"
                      },
                      "name": {
                        "type": "string"
                      },
                      "bytes": {
                        "type": "integer"
                      },
                      "sha256": {
                        "type": "string"
                      },
                      "request_id": {
                        "type": "string"
                      },
                      "options": {
                        "type": "object"
                      }
                    },
                    "additionalProperties": true
                  },
                  {
                    "type": "object",
                    "required": [
                      "action",
                      "upload_id"
                    ],
                    "properties": {
                      "action": {
                        "const": "complete"
                      },
                      "upload_id": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true
                  },
                  {
                    "type": "object",
                    "required": [
                      "action",
                      "upload_id",
                      "review_token"
                    ],
                    "properties": {
                      "action": {
                        "const": "apply"
                      },
                      "upload_id": {
                        "type": "string"
                      },
                      "review_token": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful action",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Project access required"
          },
          "409": {
            "description": "Changed state or unavailable operation"
          }
        }
      }
    },
    "/panel": {
      "get": {
        "operationId": "readRecruitmentAction",
        "security": [
          {
            "ApplicationSession": []
          }
        ],
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": true,
            "schema": {
              "enum": [
                "audience_options",
                "surveys",
                "studies",
                "study_detail"
              ]
            }
          },
          {
            "name": "project_id",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "study_id",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful action",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Project access required"
          },
          "409": {
            "description": "Changed state or unavailable operation"
          }
        }
      },
      "post": {
        "operationId": "writeRecruitmentAction",
        "security": [
          {
            "ApplicationSession": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "required": [
                      "action",
                      "project_id",
                      "filters",
                      "required_completes"
                    ],
                    "properties": {
                      "action": {
                        "const": "quote"
                      },
                      "project_id": {
                        "type": "integer"
                      },
                      "filters": {
                        "type": "object"
                      },
                      "required_completes": {
                        "type": "integer"
                      }
                    },
                    "additionalProperties": true
                  },
                  {
                    "type": "object",
                    "required": [
                      "action",
                      "project_id",
                      "survey_id",
                      "filters",
                      "required_completes",
                      "request_id",
                      "max_budget_minor"
                    ],
                    "properties": {
                      "action": {
                        "const": "create_study"
                      },
                      "project_id": {
                        "type": "integer"
                      },
                      "survey_id": {
                        "type": "integer"
                      },
                      "filters": {
                        "type": "object"
                      },
                      "required_completes": {
                        "type": "integer"
                      },
                      "request_id": {
                        "type": "string"
                      },
                      "max_budget_minor": {
                        "type": "integer"
                      }
                    },
                    "additionalProperties": true
                  },
                  {
                    "type": "object",
                    "required": [
                      "action",
                      "study_id",
                      "confirm_budget"
                    ],
                    "properties": {
                      "action": {
                        "const": "launch_study"
                      },
                      "study_id": {
                        "type": "string"
                      },
                      "confirm_budget": {
                        "type": "boolean"
                      }
                    },
                    "additionalProperties": true
                  },
                  {
                    "type": "object",
                    "required": [
                      "action",
                      "study_id"
                    ],
                    "properties": {
                      "action": {
                        "const": "pause_study"
                      },
                      "study_id": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true
                  },
                  {
                    "type": "object",
                    "required": [
                      "action",
                      "study_id"
                    ],
                    "properties": {
                      "action": {
                        "const": "cancel_study"
                      },
                      "study_id": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": true
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful action",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Project access required"
          },
          "409": {
            "description": "Changed state or unavailable operation"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ProjectKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "DatumForms project API key"
      },
      "ApplicationSession": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "DatumForms application session"
      }
    },
    "schemas": {
      "Success": {
        "type": "object",
        "required": [
          "success"
        ],
        "properties": {
          "success": {
            "const": true
          }
        },
        "additionalProperties": true
      },
      "Error": {
        "type": "object",
        "required": [
          "success",
          "message"
        ],
        "properties": {
          "success": {
            "const": false
          },
          "message": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "AnswerCell": {
        "type": "object",
        "properties": {
          "questionRef": {
            "type": "integer",
            "minimum": 1
          },
          "value": {
            "type": [
              "string",
              "number",
              "null"
            ]
          },
          "row": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 10000
          },
          "col": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 10000
          }
        },
        "required": [
          "questionRef"
        ],
        "additionalProperties": false
      },
      "SavedAnswer": {
        "type": "object",
        "properties": {
          "response_id": {
            "type": "integer"
          },
          "form_elements_id": {
            "type": "integer"
          },
          "row": {
            "type": [
              "integer",
              "null"
            ]
          },
          "col": {
            "type": [
              "integer",
              "null"
            ]
          },
          "field_response_value": {
            "type": [
              "string",
              "number",
              "null"
            ]
          }
        },
        "additionalProperties": true
      },
      "Group": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "active_nom": {
            "type": [
              "integer",
              "string"
            ]
          },
          "published_version_id": {
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "additionalProperties": true
      },
      "Response": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "collection_id": {
            "type": "integer"
          },
          "version_id": {
            "type": [
              "integer",
              "null"
            ]
          },
          "revision": {
            "type": "integer"
          },
          "status": {
            "type": "string"
          },
          "submitted_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "answers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SavedAnswer"
            }
          },
          "collection_details": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "captured_location": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "reference_location": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          }
        },
        "additionalProperties": true
      }
    }
  },
  "x-datumforms-operations": [
    {
      "operation": "account.get",
      "method": "GET",
      "permissions": [
        "account:read"
      ],
      "description": "Read the project name, type and plan summary.",
      "parameters": {},
      "response": {
        "account": {
          "id": "integer",
          "name": "string",
          "type": "integer",
          "plan_type": "string|null"
        }
      },
      "example": {},
      "url": "/docs/api/account-get/"
    },
    {
      "operation": "groups.list",
      "method": "GET",
      "permissions": [
        "groups:read"
      ],
      "description": "List up to 100 groups and their published versions. Continue with after_id.",
      "parameters": {
        "after_id": {
          "location": "query",
          "type": "integer",
          "required": false,
          "description": "Last group ID from next_cursor; omit or 0 for the first page."
        }
      },
      "response": {
        "groups": "Group[]",
        "next_cursor": "integer|null"
      },
      "example": {
        "after_id": 0
      },
      "url": "/docs/api/groups-list/"
    },
    {
      "operation": "groups.set_availability",
      "method": "POST",
      "permissions": [
        "groups:write"
      ],
      "description": "Set group_id and data.active to open or close response collection through the existing publication and plan checks.",
      "parameters": {
        "group_id": {
          "location": "query",
          "type": "integer",
          "required": true,
          "description": "Group ID returned by groups.list or groups.save."
        },
        "active": {
          "location": "data",
          "type": "boolean",
          "required": true,
          "description": "true opens collection; false closes it."
        }
      },
      "response": {
        "success": "boolean"
      },
      "example": {
        "group_id": 123,
        "data": {
          "active": false
        }
      },
      "url": "/docs/api/groups-set-availability/"
    },
    {
      "operation": "groups.save",
      "method": "POST",
      "permissions": [
        "groups:write"
      ],
      "description": "Create a group with data.name, or edit one with data.group_id.",
      "parameters": {
        "name": {
          "location": "data",
          "type": "string",
          "required": true,
          "description": "Group name, 1\u2013256 characters."
        },
        "group_id": {
          "location": "data",
          "type": "integer",
          "required": false,
          "description": "Existing group ID when editing."
        },
        "categories": {
          "location": "data",
          "type": "string",
          "required": false,
          "description": "Description."
        }
      },
      "response": {
        "group_id": "integer"
      },
      "example": {
        "data": {
          "name": "Customer feedback"
        }
      },
      "url": "/docs/api/groups-save/"
    },
    {
      "operation": "groups.assign_form",
      "method": "POST",
      "permissions": [
        "assignments:write"
      ],
      "description": "Attach data.form_id to group_id as a draft change.",
      "parameters": {
        "group_id": {
          "location": "query",
          "type": "integer",
          "required": true,
          "description": "Destination group ID."
        },
        "form_id": {
          "location": "data",
          "type": "integer",
          "required": true,
          "description": "Saved page ID returned by surveys.save."
        }
      },
      "response": {
        "success": "boolean"
      },
      "example": {
        "group_id": 123,
        "data": {
          "form_id": 456
        }
      },
      "url": "/docs/api/groups-assign-form/"
    },
    {
      "operation": "surveys.get",
      "method": "GET",
      "permissions": [
        "surveys:read"
      ],
      "description": "Read form definitions. Provide form_id for one form.",
      "parameters": {
        "form_id": {
          "location": "query",
          "type": "integer",
          "required": false,
          "description": "Select a page by its form ID; omit to list pages."
        }
      },
      "response": {
        "forms": "Form[] (list)",
        "form": "Form (single)",
        "elements": "Element[] (single)",
        "edit_hash": "string (single)"
      },
      "example": {},
      "url": "/docs/api/surveys-get/"
    },
    {
      "operation": "surveys.save",
      "method": "POST",
      "permissions": [
        "surveys:write"
      ],
      "description": "Save draft pages and elements. Existing forms require form_id and expected_edit_hash.",
      "parameters": {
        "name": {
          "location": "data",
          "type": "string",
          "required": true,
          "description": "Page name."
        },
        "elements": {
          "location": "data",
          "type": "array",
          "required": true,
          "description": "Canonical Form Studio element definitions. Each new field needs a type, client_id, caption and type-specific settings."
        },
        "form_id": {
          "location": "data",
          "type": "integer",
          "required": false,
          "description": "Existing page ID when editing."
        },
        "expected_edit_hash": {
          "location": "data",
          "type": "string",
          "required": false,
          "description": "Required when editing; from surveys.get."
        },
        "page_number": {
          "location": "data",
          "type": "integer",
          "required": false,
          "description": "Positive page order."
        },
        "purpose": {
          "location": "data",
          "type": "string",
          "required": false,
          "description": "Page purpose supported by Form Studio."
        },
        "allow_uploads": {
          "location": "data",
          "type": "boolean",
          "required": false,
          "description": "Whether the page permits attachments."
        },
        "page_logic": {
          "location": "data",
          "type": "object",
          "required": false,
          "description": "Page conditions."
        },
        "branching": {
          "location": "data",
          "type": "object",
          "required": false,
          "description": "Forward branching configuration."
        }
      },
      "response": {
        "form_id": "integer",
        "edit_hash": "string"
      },
      "example": {
        "data": {
          "name": "Service feedback",
          "elements": [
            {
              "type": "radio",
              "client_id": "rating",
              "caption": "Was your issue resolved?",
              "options": [
                {
                  "name": "Yes",
                  "value": "yes"
                },
                {
                  "name": "No",
                  "value": "no"
                }
              ]
            }
          ]
        }
      },
      "url": "/docs/api/surveys-save/"
    },
    {
      "operation": "surveys.review",
      "method": "GET",
      "permissions": [
        "surveys:read"
      ],
      "description": "Review unpublished changes for group_id; retain review_token.",
      "parameters": {
        "group_id": {
          "location": "query",
          "type": "integer",
          "required": true,
          "description": "Survey group to review."
        }
      },
      "response": {
        "surveys": "array",
        "review_token": "string"
      },
      "example": {
        "group_id": 123
      },
      "url": "/docs/api/surveys-review/"
    },
    {
      "operation": "surveys.publish",
      "method": "POST",
      "permissions": [
        "surveys:publish"
      ],
      "description": "Publish the reviewed draft with group_id and data.review_token.",
      "parameters": {
        "group_id": {
          "location": "query",
          "type": "integer",
          "required": true,
          "description": "Reviewed survey group."
        },
        "review_token": {
          "location": "data",
          "type": "string",
          "required": true,
          "description": "Fresh fingerprint returned by surveys.review."
        }
      },
      "response": {
        "success": "boolean"
      },
      "example": {
        "group_id": 123,
        "data": {
          "review_token": "REVIEW_TOKEN_FROM_SURVEYS_REVIEW"
        }
      },
      "url": "/docs/api/surveys-publish/"
    },
    {
      "operation": "assignments.save",
      "method": "POST",
      "permissions": [
        "assignments:write"
      ],
      "description": "Create an ordinary participant assignment with their existing email and groups_id.",
      "parameters": {
        "email": {
          "location": "data",
          "type": "string",
          "required": true,
          "description": "Existing participant account email."
        },
        "groups_id": {
          "location": "data",
          "type": "integer",
          "required": true,
          "description": "Survey group to assign. Does not edit an existing membership."
        }
      },
      "response": {
        "success": "boolean"
      },
      "example": {
        "data": {
          "email": "pilot@example.invalid",
          "groups_id": 123
        }
      },
      "url": "/docs/api/assignments-save/"
    },
    {
      "operation": "resources.get",
      "method": "GET",
      "permissions": [
        "resources:read"
      ],
      "description": "Read custom JavaScript/CSS resources; optionally select resource_id.",
      "parameters": {
        "resource_id": {
          "location": "query",
          "type": "integer",
          "required": false,
          "description": "Resource ID; omit for all project code resources."
        }
      },
      "response": {
        "codes": "Resource[] (list)",
        "code": "Resource (single)"
      },
      "example": {},
      "url": "/docs/api/resources-get/"
    },
    {
      "operation": "resources.save",
      "method": "POST",
      "permissions": [
        "resources:write"
      ],
      "description": "Save code_title, js_css, resource_type and resource_value; include id to edit.",
      "parameters": {
        "code_title": {
          "location": "data",
          "type": "string",
          "required": true,
          "description": "Resource title."
        },
        "js_css": {
          "location": "data",
          "type": "string",
          "required": true,
          "description": "Resource language: javascript or css."
        },
        "resource_type": {
          "location": "data",
          "type": "string",
          "required": true,
          "description": "Resource representation: code or link."
        },
        "resource_value": {
          "location": "data",
          "type": "string",
          "required": true,
          "description": "JavaScript or CSS source."
        },
        "id": {
          "location": "data",
          "type": "integer",
          "required": false,
          "description": "Existing resource ID when editing."
        }
      },
      "response": {
        "saved": "boolean",
        "id": "integer"
      },
      "example": {
        "data": {
          "code_title": "Survey styling",
          "js_css": "css",
          "resource_type": "code",
          "resource_value": ".example { color: #0f172a; }"
        }
      },
      "url": "/docs/api/resources-save/"
    },
    {
      "operation": "resources.delete",
      "method": "POST",
      "permissions": [
        "resources:delete"
      ],
      "description": "Delete the custom resource identified by data.id.",
      "parameters": {
        "id": {
          "location": "data",
          "type": "integer",
          "required": true,
          "description": "Resource ID from resources.get."
        }
      },
      "response": {
        "success": "boolean"
      },
      "example": {
        "data": {
          "id": 123
        }
      },
      "url": "/docs/api/resources-delete/"
    },
    {
      "operation": "responses.list",
      "method": "GET",
      "permissions": [
        "responses:read"
      ],
      "description": "Read paginated responses and answer cells. Optional filters (question_ref, operator, value), limit up to 1000, and include_location=true with location:read.",
      "parameters": {
        "group_id": {
          "location": "query",
          "type": "integer",
          "required": false,
          "description": "Optional group ID. All allowed groups when omitted."
        },
        "alias": {
          "location": "query",
          "type": "string",
          "required": false,
          "description": "Stable group reference; if also supplying group_id, they must agree."
        },
        "after_id": {
          "location": "query",
          "type": "integer",
          "required": false,
          "description": "Last response ID from next_cursor. Default 0."
        },
        "limit": {
          "location": "query",
          "type": "integer",
          "required": false,
          "description": "Page size, default 100, maximum 1000."
        },
        "filters": {
          "location": "query",
          "type": "string",
          "required": false,
          "description": "JSON array of question_ref, operator and value. Operators: eq, ne, in, contains; combined with AND."
        },
        "include_collection_details": {
          "location": "query",
          "type": "boolean",
          "required": false,
          "description": "Include collection_details. Needs collection:read and no field restrictions."
        },
        "include_location": {
          "location": "query",
          "type": "boolean",
          "required": false,
          "description": "Include captured_location and reference_location. Needs location:read. Anonymous and panel coordinates are null."
        }
      },
      "response": {
        "responses": "Response[]",
        "next_cursor": "integer|null"
      },
      "example": {
        "group_id": 123,
        "after_id": 0,
        "limit": 100
      },
      "url": "/docs/api/responses-list/"
    },
    {
      "operation": "responses.create",
      "method": "POST",
      "permissions": [
        "responses:create"
      ],
      "description": "Import ordinary responses with group_id, data.reason and data.answers.",
      "parameters": {
        "group_id": {
          "location": "query",
          "type": "integer",
          "required": true,
          "description": "Published ordinary collection."
        },
        "reason": {
          "location": "data",
          "type": "string",
          "required": true,
          "description": "Nonblank audit reason, up to 1000 characters."
        },
        "answers": {
          "location": "data",
          "type": "array",
          "required": true,
          "description": "1\u20132000 answer cells with questionRef, value and optional row/col."
        },
        "display_name": {
          "location": "data",
          "type": "string",
          "required": false,
          "description": "Optional display name, up to 255 characters."
        }
      },
      "response": {
        "response_id": "integer",
        "revision": "integer"
      },
      "example": {
        "group_id": 123,
        "data": {
          "reason": "Load approved item master",
          "answers": [
            {
              "questionRef": 456,
              "value": "ITEM-001"
            }
          ]
        }
      },
      "url": "/docs/api/responses-create/"
    },
    {
      "operation": "responses.update",
      "method": "POST",
      "permissions": [
        "responses:write"
      ],
      "description": "Correct ordinary answers using response_id, expected_revision, reason and answers.",
      "parameters": {
        "response_id": {
          "location": "query",
          "type": "integer",
          "required": true,
          "description": "ID from responses.list."
        },
        "expected_revision": {
          "location": "data",
          "type": "integer",
          "required": true,
          "description": "Current response revision from responses.list."
        },
        "reason": {
          "location": "data",
          "type": "string",
          "required": true,
          "description": "Nonblank reason, up to 1000 characters."
        },
        "answers": {
          "location": "data",
          "type": "array",
          "required": true,
          "description": "Answer cells in the original version; null clears a cell."
        }
      },
      "response": {
        "response_id": "integer",
        "revision": "integer"
      },
      "example": {
        "response_id": 123,
        "data": {
          "expected_revision": 1,
          "reason": "Correct item label",
          "answers": [
            {
              "questionRef": 456,
              "value": "Updated label"
            }
          ]
        }
      },
      "url": "/docs/api/responses-update/"
    },
    {
      "operation": "responses.delete",
      "method": "POST",
      "permissions": [
        "responses:delete"
      ],
      "description": "Delete an ordinary response with expected_revision and reason; files/judging history prevent deletion.",
      "parameters": {
        "response_id": {
          "location": "query",
          "type": "integer",
          "required": true,
          "description": "Ordinary response ID."
        },
        "expected_revision": {
          "location": "data",
          "type": "integer",
          "required": true,
          "description": "Current response revision."
        },
        "reason": {
          "location": "data",
          "type": "string",
          "required": true,
          "description": "Nonblank reason, up to 1000 characters."
        }
      },
      "response": {
        "deleted": "boolean",
        "response_id": "integer"
      },
      "example": {
        "response_id": 123,
        "data": {
          "expected_revision": 1,
          "reason": "Remove duplicate ordinary import"
        }
      },
      "url": "/docs/api/responses-delete/"
    },
    {
      "operation": "collection.get",
      "method": "GET",
      "permissions": [
        "collection:read"
      ],
      "description": "Read device/browser, screen/window, timing, location, survey version and received-save details for response_id. Use after_operation for more history.",
      "parameters": {
        "response_id": {
          "location": "query",
          "type": "integer",
          "required": true,
          "description": "ID from responses.list."
        },
        "after_operation": {
          "location": "query",
          "type": "string",
          "required": false,
          "description": "Collection history cursor from collection.next_cursor."
        }
      },
      "response": {
        "collection": "CollectionDetails"
      },
      "example": {
        "response_id": 123
      },
      "url": "/docs/api/collection-get/"
    },
    {
      "operation": "location.correct",
      "method": "POST",
      "permissions": [
        "location:correct"
      ],
      "description": "Annotate an ordinary response with corrected latitude/longitude, expected_revision and reason.",
      "parameters": {
        "response_id": {
          "location": "query",
          "type": "integer",
          "required": true,
          "description": "Ordinary response ID."
        },
        "expected_revision": {
          "location": "data",
          "type": "integer",
          "required": true,
          "description": "Current response revision."
        },
        "latitude": {
          "location": "data",
          "type": "number",
          "required": true,
          "description": "Latitude from -90 to 90."
        },
        "longitude": {
          "location": "data",
          "type": "number",
          "required": true,
          "description": "Longitude from -180 to 180."
        },
        "reason": {
          "location": "data",
          "type": "string",
          "required": true,
          "description": "Correction reason, up to 1000 characters."
        }
      },
      "response": {
        "response_id": "integer",
        "revision": "integer"
      },
      "example": {
        "response_id": 123,
        "data": {
          "expected_revision": 1,
          "latitude": 5.6,
          "longitude": -0.2,
          "reason": "Verified site reference"
        }
      },
      "url": "/docs/api/location-correct/"
    },
    {
      "operation": "monthly.create",
      "method": "POST",
      "permissions": [
        "groups:write",
        "surveys:write",
        "assignments:write"
      ],
      "description": "Clone a published source into a draft group using source_group_id, expected_source_version_id and name.",
      "parameters": {
        "source_group_id": {
          "location": "data",
          "type": "integer",
          "required": true,
          "description": "Published source group from groups.list."
        },
        "expected_source_version_id": {
          "location": "data",
          "type": "integer",
          "required": true,
          "description": "Its current published_version_id."
        },
        "name": {
          "location": "data",
          "type": "string",
          "required": true,
          "description": "New group name."
        }
      },
      "response": {
        "group_id": "integer",
        "draft": "boolean",
        "draft_version_id": "integer",
        "source_group_id": "integer"
      },
      "example": {
        "data": {
          "source_group_id": 123,
          "expected_source_version_id": 456,
          "name": "Next monthly audit"
        }
      },
      "url": "/docs/api/monthly-create/"
    },
    {
      "operation": "aliases.get",
      "method": "GET",
      "permissions": [
        "groups:read"
      ],
      "description": "Resolve alias to its current group_id and revision.",
      "parameters": {
        "alias": {
          "location": "query",
          "type": "string",
          "required": true,
          "description": "Lowercase-leading name, 1\u201364 letters, digits, hyphens or underscores."
        }
      },
      "response": {
        "alias": "string",
        "group_id": "integer",
        "revision": "integer"
      },
      "example": {
        "alias": "current-items"
      },
      "url": "/docs/api/aliases-get/"
    },
    {
      "operation": "aliases.set",
      "method": "POST",
      "permissions": [
        "groups:write"
      ],
      "description": "Switch data.alias to published group_id with data.expected_revision; use 0 for a new alias.",
      "parameters": {
        "group_id": {
          "location": "query",
          "type": "integer",
          "required": true,
          "description": "Published destination group."
        },
        "alias": {
          "location": "data",
          "type": "string",
          "required": true,
          "description": "Stable reference name: lowercase first letter and up to 63 lowercase letters, digits, hyphens or underscores."
        },
        "expected_revision": {
          "location": "data",
          "type": "integer",
          "required": true,
          "description": "Revision from aliases.get; 0 for a new reference."
        }
      },
      "response": {
        "alias": "string",
        "group_id": "integer",
        "revision": "integer"
      },
      "example": {
        "group_id": 123,
        "data": {
          "alias": "current-items",
          "expected_revision": 0
        }
      },
      "url": "/docs/api/aliases-set/"
    },
    {
      "operation": "lookups.save",
      "method": "POST",
      "permissions": [
        "groups:write",
        "responses:read"
      ],
      "description": "Configure a participant lookup with name, collection_aliases and question_refs. Set active:false to disable.",
      "parameters": {
        "name": {
          "location": "data",
          "type": "string",
          "required": true,
          "description": "Lowercase-leading lookup name, up to 64 characters."
        },
        "collection_aliases": {
          "location": "data",
          "type": "array",
          "required": true,
          "description": "1\u201320 existing alias names."
        },
        "question_refs": {
          "location": "data",
          "type": "array",
          "required": true,
          "description": "1\u2013500 positive question IDs."
        },
        "active": {
          "location": "data",
          "type": "boolean",
          "required": false,
          "description": "false disables the lookup; defaults true."
        }
      },
      "response": {
        "name": "string",
        "active": "boolean"
      },
      "example": {
        "data": {
          "name": "items",
          "collection_aliases": [
            "current-items"
          ],
          "question_refs": [
            456
          ]
        }
      },
      "url": "/docs/api/lookups-save/"
    },
    {
      "operation": "members.list",
      "method": "GET",
      "permissions": [
        "members:read"
      ],
      "description": "Read the permitted project participant roster, paginated with page; optionally filter by group_id.",
      "parameters": {
        "group_id": {
          "location": "query",
          "type": "integer",
          "required": false,
          "description": "Optional participant group filter."
        },
        "page": {
          "location": "query",
          "type": "integer",
          "required": false,
          "description": "Page number, starting at 1. Fixed page size 100."
        }
      },
      "response": {
        "members": "array; see returned membership fields",
        "total": "integer",
        "page": "integer"
      },
      "example": {
        "group_id": 123,
        "page": 1
      },
      "url": "/docs/api/members-list/"
    },
    {
      "operation": "sheets.status",
      "method": "GET",
      "permissions": [
        "sheets:read"
      ],
      "description": "Read the connected spreadsheet and refresh state for group_id.",
      "parameters": {
        "group_id": {
          "location": "query",
          "type": "integer",
          "required": true,
          "description": "Group whose connected export to inspect."
        }
      },
      "response": {
        "group_id": "integer",
        "refresh_pending": "boolean",
        "revision": "integer",
        "spreadsheet_id": "string"
      },
      "example": {
        "group_id": 123
      },
      "url": "/docs/api/sheets-status/"
    },
    {
      "operation": "sheets.refresh",
      "method": "POST",
      "permissions": [
        "sheets:write"
      ],
      "description": "Queue the existing Google Sheets export for group_id.",
      "parameters": {
        "group_id": {
          "location": "query",
          "type": "integer",
          "required": true,
          "description": "Group whose existing Sheets connection to refresh."
        }
      },
      "response": {
        "group_id": "integer",
        "refresh_pending": "boolean",
        "revision": "integer",
        "spreadsheet_id": "string"
      },
      "example": {
        "group_id": 123,
        "data": {}
      },
      "url": "/docs/api/sheets-refresh/"
    },
    {
      "operation": "keys.lookup_groups",
      "method": "GET",
      "permissions": [
        "keys:lookup"
      ],
      "description": "Read the group policies of read-only lookup keys. Secrets are never returned.",
      "parameters": {},
      "response": {
        "keys": "array of {id:integer,name:string,collection_ids:integer[]}"
      },
      "example": {},
      "url": "/docs/api/keys-lookup-groups/"
    },
    {
      "operation": "keys.update_lookup_groups",
      "method": "POST",
      "permissions": [
        "keys:lookup"
      ],
      "description": "Update a read-only lookup key using key_id, collection_ids and expected_collection_ids.",
      "parameters": {
        "key_id": {
          "location": "data",
          "type": "integer",
          "required": true,
          "description": "Read-only key ID from keys.lookup_groups."
        },
        "collection_ids": {
          "location": "data",
          "type": "array",
          "required": true,
          "description": "1\u2013500 permitted group IDs."
        },
        "expected_collection_ids": {
          "location": "data",
          "type": "array",
          "required": true,
          "description": "Exact current array from keys.lookup_groups."
        }
      },
      "response": {
        "key_id": "integer",
        "collection_ids": "integer[]"
      },
      "example": {
        "data": {
          "key_id": 123,
          "collection_ids": [
            456
          ],
          "expected_collection_ids": [
            789
          ]
        }
      },
      "url": "/docs/api/keys-update-lookup-groups/"
    },
    {
      "operation": "recruitment.stop",
      "method": "POST",
      "permissions": [
        "recruitment:stop"
      ],
      "description": "Pause new recruitment for data.study_id; existing reservation rules still apply.",
      "parameters": {
        "study_id": {
          "location": "data",
          "type": "string",
          "required": true,
          "description": "Study UUID from the recruitment study result."
        }
      },
      "response": {
        "success": "boolean"
      },
      "example": {
        "data": {
          "study_id": "11111111-1111-4111-8111-111111111111"
        }
      },
      "url": "/docs/api/recruitment-stop/"
    }
  ]
}
