Fillo Settings API

openapi: 3.2.0
info:
  title: Fillo So Settings API
  version: 1.0.0
  contact:
    name: Fillo support
    email: hello@fillo.so
    url: https://fillo.so/developers
  description: 'Operations tagged Settings across 2 of this provider''s published API definitions: fillo-so-openapi.json, fillo-so-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://fillo.so
security:
- bearerAuth: []
tags:
- name: Settings
paths:
  /api/v1/manage/forms/{form}/settings:
    get:
      tags:
      - Settings
      summary: Get a form's settings
      operationId: getFormSettings
      description: 'The form''s current operational settings (notifications, receipts, save-and-resume, response limits, and the like). Scope: settings:manage.'
      parameters:
      - $ref: '#/components/parameters/FormHandle'
      responses:
        '200':
          description: The form's settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSettingsEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    patch:
      tags:
      - Settings
      summary: Patch a form's settings
      operationId: updateFormSettings
      description: 'Update one or more operational settings. The request body IS the settings patch object, validated and saved by the same writer as the dashboard; any key set to null is cleared. Scope: settings:manage — plus forms:write whenever the patch names one of the six presentation keys (submitMode, submitLabel, successTitle, successMessage, redirectUrl, showProgress), which live inside the form schema rather than beside it. The 403 names the missing scope.'
      parameters:
      - $ref: '#/components/parameters/FormHandle'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormSettings'
      responses:
        '200':
          description: The updated settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormSettingsEnvelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The patch conflicts with the form's current state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://fillo.so
components:
  schemas:
    FormSettingsEnvelope:
      type: object
      required:
      - settings
      properties:
        settings:
          $ref: '#/components/schemas/FormSettings'
    FormSettings:
      type: object
      description: 'A partial FormSettings patch (see @usefillo/core FormSettings): booleans such as notifyEmailIncludeAnswers, sendReceipt, saveProgress, draftAnswersVisible, resumeEmails, and draftDigest; strings such as notifyEmail, notifyEmailReplyToField, and resumeUrl; an array notifyEmailAnswerFields; and objects such as responseLimit and trust. Any key set to null is cleared. Six of the keys are not operational settings but part of the form''s definition — submitMode, submitLabel, successTitle, successMessage, redirectUrl, and showProgress live inside the form schema: patching any of them additionally requires forms:write, and code-managed forms reject them outright.'
      additionalProperties: true
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
  responses:
    NotFound:
      description: No such resource in this project (returned instead of 403 for ids in other projects).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Per-key (120/min), per-workspace (240/min), or per-IP (300/min) rate limit exceeded. Retry after the Retry-After header.
      headers:
        RateLimit-Policy:
          description: Named quota policies and their limits/windows.
          schema:
            type: string
        RateLimit:
          description: Current remaining quota and seconds until reset for each named policy.
          schema:
            type: string
        RateLimit-Limit:
          description: 'Compatibility field: effective request limit.'
          schema:
            type: integer
        RateLimit-Remaining:
          description: 'Compatibility field: effective requests remaining.'
          schema:
            type: integer
        RateLimit-Reset:
          description: 'Compatibility field: seconds until the effective window resets.'
          schema:
            type: integer
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The key is valid but lacks the required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, malformed, unknown, revoked, or expired key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request (e.g. a body on a GET/DELETE, or a missing required query parameter).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    FormHandle:
      name: form
      in: path
      required: true
      description: A form id or slug.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'A project secret key (`fsk_…`). Scopes: forms:read, responses:read, respondents:read, responses:export, forms:write, forms:publish, storage:manage, webhooks:manage, settings:manage, integrations:manage, responses:manage, members:manage, workspace:manage, forms:delete, responses:delete, respondents:delete, workspace:delete. A request for a scope the key lacks returns 403 with a stable message naming the scope (e.g. `This key lacks the responses:export scope.`).'
externalDocs:
  description: Fillo developer resources
  url: https://fillo.so/developers
x-refined-from:
- fillo-so-openapi.json
- fillo-so-openapi.json
x-provenance:
  method: harvested
  publisher: Fillo
  source: https://fillo.so/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)