Fillo Deliveries API

openapi: 3.2.0
info:
  title: Fillo So Deliveries API
  version: 1.0.0
  contact:
    name: Fillo support
    email: hello@fillo.so
    url: https://fillo.so/developers
  description: 'Operations tagged Deliveries 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: Deliveries
paths:
  /api/v1/manage/forms/{form}/deliveries:
    get:
      tags:
      - Deliveries
      summary: Get delivery health and recent activity
      operationId: getFormDeliveries
      description: 'Per-destination delivery health plus the bounded recent-delivery list — exactly what the form''s Activity page shows. Counts cover the telemetry retention window, not all time. Destinations are NAMED rather than spelled out: a webhook''s target URL is the credential that authorizes posting to it, so a connector-owned hook is labelled by its connector (“Zapier”, “n8n”) and any other webhook by its host plus a short fingerprint of its path. The dashboard''s Activity page is where a signed-in member reads the full URL. Scope: responses:manage.'
      parameters:
      - $ref: '#/components/parameters/FormHandle'
      responses:
        '200':
          description: Destination health and recent deliveries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryHealth'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://fillo.so
  /api/v1/manage/forms/{form}/deliveries/retry:
    post:
      tags:
      - Deliveries
      summary: Retry failed deliveries
      operationId: retryFormDeliveries
      description: 'Repair deliveries that failed or are overdue. Send exactly one target: `responseIds` (repair those responses'' newest occurrence), `destinationKey` (one destination''s backlog), `deliveryKind` + `deliveryId` (one row), or `all: true` (the form''s whole failed backlog). A retry re-sends work that was already meant to go out, so it is routine (Tier A). Scope: responses:manage.'
      parameters:
      - $ref: '#/components/parameters/FormHandle'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: []
              properties:
                responseIds:
                  type: array
                  maxItems: 200
                  items:
                    type: string
                    minLength: 1
                    maxLength: 128
                destinationKey:
                  type: string
                  minLength: 1
                  maxLength: 128
                  description: A `key` from the delivery-health destinations list.
                deliveryKind:
                  type: string
                  enum:
                  - webhook
                  - integration
                deliveryId:
                  type: string
                  minLength: 1
                  maxLength: 128
                all:
                  type: boolean
                  enum:
                  - true
              description: Exactly one target. deliveryKind and deliveryId are required together.
      responses:
        '200':
          description: How many deliveries were queued again.
          content:
            application/json:
              schema:
                type: object
                required:
                - retried
                properties:
                  retried:
                    type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://fillo.so
  /api/v1/manage/forms/{form}/deliveries/redeliver:
    post:
      tags:
      - Deliveries
      summary: Re-send responses to every destination
      operationId: redeliverFormResponses
      description: 'Send responses to every current destination again as a new delivery. This is not a repair: receivers that are not idempotent will see duplicates, which makes it outward-facing (Tier B). Held responses are never redelivered. Scope: responses:manage.'
      parameters:
      - $ref: '#/components/parameters/FormHandle'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - responseIds
              properties:
                responseIds:
                  type: array
                  maxItems: 200
                  items:
                    type: string
                    minLength: 1
                    maxLength: 128
                  minItems: 1
      responses:
        '200':
          description: How many responses were sent again.
          content:
            application/json:
              schema:
                type: object
                required:
                - redelivered
                properties:
                  redelivered:
                    type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
    servers:
    - url: https://fillo.so
components:
  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'
    PayloadTooLarge:
      description: The request body exceeded the 16 KiB management cap.
      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
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    DeliveryHealth:
      type: object
      required:
      - windowDays
      - destinations
      - deliveries
      - hasMore
      properties:
        windowDays:
          type: integer
          description: The telemetry retention window the counts cover. They are not all-time totals.
        destinations:
          type: array
          items:
            type: object
            required:
            - key
            - kind
            - label
            - detail
            - delivered
            - pending
            - failed
            - nextRetryAt
            - lastDeliveredAt
            - failingSince
            - lastError
            properties:
              key:
                type: string
                description: '`webhook:<id>` or `integration:<id>` — the value the retry endpoint accepts as destinationKey.'
              kind:
                type: string
                enum:
                - webhook
                - integration
              label:
                type: string
                description: 'How to name this destination: the provider for an integration, and for a webhook the connector that created it (“Zapier”, “n8n”) or its host plus a short fingerprint of the path. The full URL is never returned here.'
              detail:
                type:
                - string
                - 'null'
              delivered:
                type: integer
              pending:
                type: integer
              failed:
                type: integer
              nextRetryAt:
                type:
                - integer
                - 'null'
              lastDeliveredAt:
                type:
                - integer
                - 'null'
              failingSince:
                type:
                - integer
                - 'null'
              lastError:
                type:
                - string
                - 'null'
        deliveries:
          type: array
          description: The bounded recent-delivery list, newest first — the same rows the form's Activity page shows.
          items:
            type: object
            required:
            - id
            - destinationKey
            - kind
            - destinationLabel
            - destinationDetail
            - event
            - state
            - attempts
            - httpStatus
            - lastError
            - responseId
            - nextAttemptAt
            - queuedAt
            - updatedAt
            properties:
              id:
                type: string
              destinationKey:
                type: string
              kind:
                type: string
                enum:
                - webhook
                - integration
              destinationLabel:
                type: string
                description: The same name as the matching destination's label — never a full webhook URL.
              destinationDetail:
                type:
                - string
                - 'null'
              event:
                type: string
                enum:
                - response.created
                - response.updated
                - draft.abandoned
              state:
                type: string
                enum:
                - pending
                - delivered
                - failed
              attempts:
                type: integer
              httpStatus:
                type:
                - integer
                - 'null'
              lastError:
                type:
                - string
                - 'null'
              responseId:
                type:
                - string
                - 'null'
              nextAttemptAt:
                type:
                - integer
                - 'null'
              queuedAt:
                type: integer
              updatedAt:
                type: integer
        hasMore:
          type: boolean
      description: Epoch-millisecond timestamps throughout, matching the dashboard's Activity data.
  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)