> ## Documentation Index > Fetch the complete documentation index at: https://formhug.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Update a public query > **Required scope:** `form:write`. Only keys you send change, and within `search_button` and `messages` only the sub-keys you send; rule lists and `scope_conditions` are replaced as a whole. ## OpenAPI ````yaml /api-reference/openapi.yaml patch /api/v1/opensearch/queries/{token} openapi: 3.0.1 info: title: FormHug API V1 version: v1 description: > FormHug public REST API. All request/response keys are snake_case. Successful response: ```json { "data": { ... } } ``` Paginated response: ```json { "data": [ ... ], "pagination": { "total": 123, "next_cursor": "NQ==" } } ``` Error response: ```json { "error": "Human-readable message", "code": "password_required", "error_details": [ { "attribute": "field_name", "message": "specific error" } ] } ``` `code` is a machine-readable reason, present only where a client may need to branch on it (see `CodedErrorEnvelope`). `error_details` appears on validation failures and lists each offending attribute. servers: - url: https://formhug.ai security: [] tags: - name: Forms description: Form CRUD - name: Attachments description: >- 2-step upload for form-element images (theme, rich-text, or field-element images). Prepare returns an `upload_id`; consume it in a theme update, attachment_commitments, or the form `fields` payload depending on purpose. - name: Entries description: Entries collected by a form owned by the current user - name: Folders description: Folder CRUD - name: Participated Forms description: Forms the current user has submitted to (does not own) - name: Published Form Entries description: Submit entries to a published form - name: Published Forms description: Read a published form's public structure for filling - name: Linked Form Options description: >- Discover candidate entries (and their `entry_token`s) for a `linked_form` field while filling a published form - name: Entry Attachments description: >- 2-step upload for `attachment` field submissions. Prepare returns an `upload_id`; submit it under the attachment field in `field_values` when creating the entry. - name: Me description: Current authenticated user - name: Webhooks description: Webhook integrations attached to a form - name: Form Themes description: Read and update a form's visual theme - name: Form Settings description: >- Per-form settings — submission flow, availability, access control, presentation - name: Field Rules description: >- Read and replace a form's conditional field-display and post-submission redirect rules. - name: Form Folder description: Per-user folder placement for a shared form - name: OAuth description: OAuth 2.0 PKCE token issuance and revocation - name: Public Queries description: Public query pages that let visitors look up entries by chosen fields paths: /api/v1/opensearch/queries/{token}: parameters: - name: token in: path description: Query token required: true schema: type: string patch: tags: - Public Queries summary: Update a public query description: >- **Required scope:** `form:write`. Only keys you send change, and within `search_button` and `messages` only the sub-keys you send; rule lists and `scope_conditions` are replaced as a whole. parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/OpensearchQueryUpdateRequest' responses: '200': description: Updated content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/OpensearchQuery' '402': description: Editable display fields need a higher plan content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '422': description: Undocumented key content: application/json: schema: $ref: '#/components/schemas/ValidationErrorEnvelope' security: - PersonalAccessToken: - form:write components: schemas: OpensearchQueryUpdateRequest: type: object additionalProperties: false properties: name: type: string example: Exam results description: type: string nullable: true enabled: type: boolean description: Whether the public page accepts searches. allow_to_export_results: type: boolean search_button: type: object additionalProperties: false properties: text: type: string color: type: string messages: type: object additionalProperties: false properties: has_result: type: string description: Shown above results. no_result: type: string description: Shown when nothing matches. header: type: object additionalProperties: false properties: background_image: type: object nullable: true additionalProperties: false description: >- Header background image. Provide exactly one of `id` (an image already attached to a query in your organization) or `upload_id` (a prepared upload with purpose `opensearch_header_image`). `null` removes the image. properties: id: type: string upload_id: type: string position_x: type: number nullable: true description: Horizontal focal point, percent. position_y: type: number nullable: true description: Vertical focal point, percent. search_field_rules: type: array minItems: 1 items: type: object additionalProperties: false required: - operand - fields properties: operand: type: string enum: - and - or description: >- `and`: visitors must fill every field in the group; `or`: any one of them. fields: type: array minItems: 1 items: type: object additionalProperties: false required: - field properties: field: type: string description: >- api_code of a searchable field; see the allowed fields in `search_field_rules`. example: field_1 label: type: string nullable: true description: Label shown to visitors; defaults to the field label. fuzzy: type: boolean default: false description: >- Match by "contains" instead of exact value. Allowed on short_text, long_text, name, phone, email, date, radio, dropdown, cascade, the two booking sub-fields and `gen_code`. On `date` it matches a date prefix (e.g. `2024-06` matches every day of that month). description: >- Search field groups; every group must be satisfied. Replaces the existing groups. A field may appear only once across all groups. Searchable fields (`fields[].field`): - Form fields of type short_text, long_text, name, phone, email, number, date, radio, dropdown, cascade and linked_form. - The two sub-fields of a booking field: `_attribute_api_code` (booked item) and `_attribute_date_time` (booked time). - System fields: `serial_number`; `exam_score` (exam forms); `gen_code` (forms with verification codes). - Linked-form sub-fields that are publicly displayable and searchable by the rules above, including the linked form's `serial_number`, as `_associated_`. A field outside this set is rejected with 422, and the error message lists the allowed api_codes for the form. display_field_rules: type: array minItems: 1 items: type: object additionalProperties: false required: - field properties: field: type: string description: >- api_code of a displayable field; see the allowed fields in `display_field_rules`. example: field_2 label: type: string nullable: true editable: type: boolean default: false description: >- Visitors may edit this value on the result page. Requires a plan with editable results (otherwise 402). Allowed on displayable fields of this form whose api_code is `field_N`; in exam forms, only on questions that are not scored. protected: type: boolean default: false description: >- Mask the value (privacy protection). Takes effect on name, phone and email fields, including linked-form sub-fields of those types. highlight: type: object nullable: true additionalProperties: false properties: color: type: string position: type: integer description: >- Fields shown on each result. Replaces the existing list. A field may appear only once. Displayable fields (`field`): - Form fields of type short_text, long_text, name, phone, email, number, date, time, radio, checkbox, image_radio, image_checkbox, dropdown, cascade, url, address, rating, nps, attachment, audio, signature, ranking, matrix, matrix_rating, likert, location, product, booking and linked_form. - System fields: `serial_number`, `created_at`, `updated_at`, `info_filling_duration`; `total_price` and `preferential_price` (forms with products); `reservation_status_fsf_field` (booking status, forms with bookings); `exam_score` (exam forms); `x_field_certificate` (forms with certificates); `gen_code` (forms with verification codes); `evaluation_report` (evaluation forms). - Linked-form sub-fields that are publicly displayable, as `_associated_`. A field outside this set is rejected with 422, and the error message lists the allowed api_codes for the form. scope_conditions: $ref: '#/components/schemas/FilterConditions' description: >- Limit which entries visitors can find, using the entries filter syntax (all ANDed). `[]` removes the limit. Requires a plan with scoped data. OpensearchQuery: type: object required: - token - form_token - url - status - name - enabled - search_field_rules - display_field_rules - scope_conditions - created_at - updated_at properties: token: type: string example: aB3dE form_token: type: string nullable: true description: Form the query reads from; null when the form was deleted. url: type: string format: uri description: Public page URL. status: type: string enum: - active - entries_count_limited - form_not_found description: >- `entries_count_limited`: the form has more entries than the plan allows; `form_not_found`: the form was deleted. name: type: string description: type: string nullable: true enabled: type: boolean allow_to_export_results: type: boolean search_button: type: object additionalProperties: false properties: text: type: string color: type: string messages: type: object additionalProperties: false properties: has_result: type: string description: Shown above results. no_result: type: string description: Shown when nothing matches. header: type: object properties: background_image: type: object nullable: true properties: id: type: string image_url: type: string position_x: type: number nullable: true position_y: type: number nullable: true search_field_rules: type: array items: type: object additionalProperties: false required: - operand - fields properties: operand: type: string enum: - and - or description: >- `and`: visitors must fill every field in the group; `or`: any one of them. fields: type: array minItems: 1 items: type: object additionalProperties: false required: - field properties: field: type: string description: >- api_code of a searchable field; see the allowed fields in `search_field_rules`. example: field_1 label: type: string nullable: true description: Label shown to visitors; defaults to the field label. fuzzy: type: boolean default: false description: >- Match by "contains" instead of exact value. Allowed on short_text, long_text, name, phone, email, date, radio, dropdown, cascade, the two booking sub-fields and `gen_code`. On `date` it matches a date prefix (e.g. `2024-06` matches every day of that month). display_field_rules: type: array items: type: object additionalProperties: false required: - field properties: field: type: string description: >- api_code of a displayable field; see the allowed fields in `display_field_rules`. example: field_2 label: type: string nullable: true editable: type: boolean default: false description: >- Visitors may edit this value on the result page. Requires a plan with editable results (otherwise 402). Allowed on displayable fields of this form whose api_code is `field_N`; in exam forms, only on questions that are not scored. protected: type: boolean default: false description: >- Mask the value (privacy protection). Takes effect on name, phone and email fields, including linked-form sub-fields of those types. highlight: type: object nullable: true additionalProperties: false properties: color: type: string position: type: integer scope_conditions: $ref: '#/components/schemas/FilterConditions' searches_count: type: integer views_count: type: integer created_at: type: string format: date-time updated_at: type: string format: date-time ErrorEnvelope: type: object required: - error properties: error: type: string description: Error message ValidationErrorEnvelope: type: object required: - error - error_details description: >- Returned on model validation failures. error_details lists per-field errors. properties: error: type: string example: Name can't be blank error_details: type: array items: type: object required: - attribute - message properties: attribute: type: string example: name message: type: string example: can't be blank FilterConditions: type: array description: Filter conditions, all ANDed together. items: $ref: '#/components/schemas/FilterCondition' FilterCondition: type: object required: - field - operator description: > A single filter condition. `field` is a form field `api_code`, a sub-field reference, or an entry system key: - `field_N.field_M` — a table/matrix sub-field (parent `api_code`, dot, sub-field `api_code`). - `field_N_associated_` — a field of the form linked by a linked-form field `field_N` (filters on the linked entry's value). - `serial_number`, `created_at`, `updated_at` — the entry's own attributes, the same keys `sort` takes. Table and linked-form fields cannot be filtered directly — filter their sub-fields. Matrix and likert fields are not filterable. The system keys are ordinary fields: `serial_number` filters like a `number` field and `created_at` / `updated_at` like a `date` field, with the same operators and value shapes — including the whole-day reading of a date-only value such as `2024-06-22` in the form's timezone. Which `operator`s are valid, and the shape of `value`, depend on the (sub-)field's `type`. `like` / `not_like` always take a single string (substring match). Omit `value` for `null` / `not_null`. Per type: - text-like (`short_text`, `long_text`, `email`, `phone`, `name`, `url`): `eq`, `ne`, `any_in`, `none_in`, `like`, `not_like`, `null`, `not_null`. `value` is a string; `any_in` / `none_in` take an array of strings. - `number`: `eq`, `ne`, `any_in`, `none_in`, `gt`, `gte`, `lt`, `lte`, `between`, `not_between`, `null`, `not_null`. `value` is a number; `between` / `not_between` take a two-element array. - `date`: `eq`, `ne`, `any_in`, `none_in`, `gt`, `gte`, `lt`, `lte`, `between`, `not_between`, `like`, `null`, `not_null`. `value` is an ISO 8601 date/time string (e.g. `2024-06-22T14:30:00+08:00` or `2024-06-22 14:30:00`). A value with an explicit UTC offset or `Z` is honored as given; a value without one is interpreted in the form's configured timezone. `between` takes a two-element array. - `time`: `eq`, `ne`, `any_in`, `none_in`, `like`, `null`, `not_null`. `value` is a 24-hour clock string `HH:MM` (or `HH:MM:SS`); `any_in` / `none_in` take an array of them. - choice fields (`dropdown`, `radio`, `checkbox`, `image_radio`, `image_checkbox`): `eq`, `ne`, `any_in`, `none_in`, `like`, `null`, `not_null`. `value` is a choice `api_code` (a single one for `eq` / `ne`; an array for `any_in` / `none_in`). For multi-select (`checkbox`), `eq` means the selected set equals the given set exactly — to match entries that merely include a choice, use `any_in`. `like` matches a choice's display label (the human text), not its `api_code`. - `nps`, `rating`: `eq`, `ne`, `any_in`, `none_in`, `gt`, `gte`, `lt`, `lte`, `null`, `not_null`. `value` is the numeric score. - `cascade`: `eq`, `ne`, `any_in`, `none_in`, `like`, `null`, `not_null`. `value` is an object of `level_N` keys (or an array of such objects); a partial path matches as a prefix. - `address`: `eq`, `ne`, `any_in`, `none_in`, `like`, `null`, `not_null`. `value` is an object with `address_line1`, `address_line2`, `city`, `state`, `postal_code`, `country` (or an array of such objects). - `product`: `any_in`, `none_in`, `like`, `null`, `not_null`. `value` is an array whose items are a product `api_code` string or an object `{ "api_code": ..., "specs": [ ... ] }`. - `booking`: filtered two ways, inferred from the operator and value. By reserved item — `eq`, `ne`, `any_in`, `none_in`, `null`, `not_null` with a reservation item `api_code` (a single one, or an array for `any_in` / `none_in`). By reserved date — `eq`, `ne`, `any_in`, `none_in`, `gt`, `gte`, `lt`, `lte`, `between`, `not_between` with a date/time string (a date-only operator, or a date-looking value, selects this mode). - `attachment`, `signature`: `null` / `not_null` only (`attachment` also supports `like` on the file name). - some field types are not filterable at all (e.g. `location`, `audio`, matrix, likert); a condition on one of them is rejected. properties: field: type: string description: Form field api_code example: field_1 operator: type: string enum: - any_in - between - eq - gt - gte - like - lt - lte - ne - none_in - not_between - not_like - not_null - 'null' description: >- Filter operator. The full set is listed here; which ones are valid depends on the field `type` (see above). example: eq value: description: Comparison value; shape depends on operator and field type example: Alice securitySchemes: PersonalAccessToken: type: http scheme: bearer bearerFormat: PAT description: > Personal Access Token prefixed with `fh_`. Sent as `Authorization: Bearer fh_xxx`. The scope required by each endpoint is listed in that endpoint's description. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.