{
  "openapi": "3.0.3",
  "info": {
    "title": "SwitchForms JSON API",
    "version": "1.0.0",
    "description": "Public API reference; no API key required to read this documentation. Requests require a private server-side sf_live_ key scoped to the selected published form/survey. Growth and Scale only. Keys stay in memory in this reference and clear on reload; never place them in a URL or client application. The examples are fictional placeholders, not a runnable user contract. Submission tests are real responses. All authentication, ownership, plan and quota checks remain in force. Authentication attempts are limited to 600/minute per hashed IP. See https://switchforms.app/app/help/api-integration-guide for setup and safe retries. MCP and authenticated portal APIs are separate interfaces and are not included here."
  },
  "servers": [
    {
      "url": "https://api.switchforms.app"
    }
  ],
  "tags": [
    {
      "name": "Submissions"
    },
    {
      "name": "Survey results"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "sf_live_<public-id>.<secret>",
        "description": "Private server API key with the operation's permission and selected form scope. Never use your Clerk session token here."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "details": {
                "description": "Error-specific validation issues or context; omitted when unavailable."
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "SubmissionReceipt": {
        "type": "object",
        "properties": {
          "submission": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "submittedAt": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "id",
              "submittedAt"
            ]
          },
          "usage": {
            "type": "object",
            "properties": {
              "remaining": {
                "type": "integer"
              },
              "collectionLimit": {
                "type": "integer"
              },
              "periodEnd": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "remaining",
              "collectionLimit",
              "periodEnd"
            ]
          },
          "outcome": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "action": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "link",
                      "redirect"
                    ]
                  },
                  "url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "label": {
                    "type": "string"
                  }
                },
                "required": [
                  "type",
                  "url"
                ]
              }
            },
            "required": [
              "id",
              "title",
              "message"
            ]
          }
        },
        "required": [
          "submission",
          "usage",
          "outcome"
        ]
      },
      "SurveySchema": {
        "type": "object",
        "properties": {
          "schema": {
            "type": "string",
            "enum": [
              "switchforms.survey-results.v1"
            ]
          },
          "form": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "kind": {
                "type": "string",
                "enum": [
                  "survey"
                ]
              },
              "version": {
                "type": "integer"
              },
              "publicationNumber": {
                "type": "integer"
              },
              "publishedAt": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "id",
              "slug",
              "name",
              "kind",
              "version",
              "publicationNumber",
              "publishedAt"
            ]
          },
          "questions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "required": {
                  "type": "boolean"
                },
                "answer": {
                  "type": "object",
                  "description": "Dynamic answer contract for this immutable question. May include types, machine values, bounds, matrix rows or constant-sum target. File answers are omitted from results."
                },
                "options": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "value": {
                        "type": "string"
                      },
                      "label": {
                        "type": "string"
                      },
                      "disabled": {
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "id",
                      "value",
                      "label",
                      "disabled"
                    ]
                  }
                },
                "rows": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "label": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "id",
                      "label"
                    ]
                  }
                }
              },
              "required": [
                "id",
                "type",
                "label",
                "required",
                "answer"
              ]
            }
          },
          "resultQuery": {
            "type": "object",
            "properties": {
              "endpoint": {
                "type": "string"
              },
              "method": {
                "type": "string",
                "enum": [
                  "POST"
                ]
              },
              "contentType": {
                "type": "string",
                "enum": [
                  "application/json"
                ]
              },
              "filters": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "endpoint",
              "method",
              "contentType",
              "filters"
            ]
          }
        },
        "required": [
          "schema",
          "form",
          "questions",
          "resultQuery"
        ]
      },
      "QuestionAnalysis": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "completion"
                ]
              }
            },
            "required": [
              "kind"
            ]
          },
          {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "categorical"
                ]
              },
              "values": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "value": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "percentage": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "value",
                    "label",
                    "count",
                    "percentage"
                  ]
                }
              }
            },
            "required": [
              "kind",
              "values"
            ]
          },
          {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "numeric"
                ]
              },
              "average": {
                "type": "number",
                "nullable": true
              },
              "median": {
                "type": "number",
                "nullable": true
              },
              "minimum": {
                "type": "number",
                "nullable": true
              },
              "maximum": {
                "type": "number",
                "nullable": true
              },
              "values": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "value": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "percentage": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "value",
                    "label",
                    "count",
                    "percentage"
                  ]
                }
              }
            },
            "required": [
              "kind",
              "average",
              "median",
              "minimum",
              "maximum",
              "values"
            ]
          },
          {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "nps"
                ]
              },
              "score": {
                "type": "number",
                "nullable": true
              },
              "promoters": {
                "type": "integer"
              },
              "passives": {
                "type": "integer"
              },
              "detractors": {
                "type": "integer"
              },
              "values": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "value": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "percentage": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "value",
                    "label",
                    "count",
                    "percentage"
                  ]
                }
              }
            },
            "required": [
              "kind",
              "score",
              "promoters",
              "passives",
              "detractors",
              "values"
            ]
          },
          {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "csat",
                  "ces"
                ]
              },
              "score": {
                "type": "number",
                "nullable": true
              },
              "favorable": {
                "type": "integer"
              },
              "average": {
                "type": "number",
                "nullable": true
              },
              "values": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "value": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "percentage": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "value",
                    "label",
                    "count",
                    "percentage"
                  ]
                }
              }
            },
            "required": [
              "kind",
              "score",
              "favorable",
              "average",
              "values"
            ]
          },
          {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "text"
                ]
              },
              "averageCharacters": {
                "type": "number",
                "nullable": true
              },
              "topTerms": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "term": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "term",
                    "count"
                  ]
                }
              },
              "sentiment": {
                "type": "object",
                "properties": {
                  "positive": {
                    "type": "integer"
                  },
                  "neutral": {
                    "type": "integer"
                  },
                  "negative": {
                    "type": "integer"
                  }
                },
                "required": [
                  "positive",
                  "neutral",
                  "negative"
                ]
              },
              "themes": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "label": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "terms": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "label",
                    "count",
                    "terms"
                  ]
                }
              }
            },
            "required": [
              "kind",
              "averageCharacters",
              "topTerms"
            ]
          },
          {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "ranking"
                ]
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "value": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    },
                    "averageRank": {
                      "type": "number"
                    },
                    "firstChoiceCount": {
                      "type": "integer"
                    },
                    "responseCount": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "value",
                    "label",
                    "averageRank",
                    "firstChoiceCount"
                  ]
                }
              }
            },
            "required": [
              "kind",
              "items"
            ]
          },
          {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "matrix"
                ]
              },
              "rows": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "rowId": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    },
                    "values": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "value": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "count": {
                            "type": "integer"
                          },
                          "percentage": {
                            "type": "number"
                          }
                        },
                        "required": [
                          "value",
                          "label",
                          "count",
                          "percentage"
                        ]
                      }
                    }
                  },
                  "required": [
                    "rowId",
                    "label",
                    "values"
                  ]
                }
              }
            },
            "required": [
              "kind",
              "rows"
            ]
          },
          {
            "type": "object",
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "constantSum"
                ]
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "value": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    },
                    "average": {
                      "type": "number"
                    },
                    "total": {
                      "type": "number"
                    },
                    "responseCount": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "value",
                    "label",
                    "average",
                    "total"
                  ]
                }
              }
            },
            "required": [
              "kind",
              "items"
            ]
          }
        ]
      },
      "SurveyResults": {
        "type": "object",
        "properties": {
          "schema": {
            "type": "string",
            "enum": [
              "switchforms.survey-results.v1"
            ]
          },
          "results": {
            "type": "object",
            "properties": {
              "range": {
                "type": "object",
                "properties": {
                  "from": {
                    "type": "string",
                    "nullable": true
                  },
                  "to": {
                    "type": "string",
                    "nullable": true
                  }
                },
                "required": [
                  "from",
                  "to"
                ]
              },
              "responseCount": {
                "type": "integer"
              },
              "versions": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "integer"
                    },
                    "publicationNumber": {
                      "type": "integer",
                      "nullable": true
                    },
                    "title": {
                      "type": "string"
                    },
                    "responseCount": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "version",
                    "publicationNumber",
                    "title",
                    "responseCount"
                  ]
                }
              },
              "trend": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "date": {
                      "type": "string"
                    },
                    "version": {
                      "type": "integer"
                    },
                    "responses": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "date",
                    "version",
                    "responses"
                  ]
                }
              },
              "questions": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "integer"
                    },
                    "publicationNumber": {
                      "type": "integer",
                      "nullable": true
                    },
                    "fieldId": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    },
                    "fieldType": {
                      "type": "string"
                    },
                    "answered": {
                      "type": "integer"
                    },
                    "skipped": {
                      "type": "integer"
                    },
                    "responseRate": {
                      "type": "number"
                    },
                    "analysis": {
                      "$ref": "#/components/schemas/QuestionAnalysis"
                    },
                    "privacySuppressed": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "version",
                    "publicationNumber",
                    "fieldId",
                    "label",
                    "fieldType",
                    "answered",
                    "skipped",
                    "responseRate",
                    "analysis"
                  ]
                }
              },
              "crossTab": {
                "type": "object",
                "properties": {
                  "version": {
                    "type": "integer"
                  },
                  "rowField": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "label": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "id",
                      "label"
                    ]
                  },
                  "columnField": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "label": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "id",
                      "label"
                    ]
                  },
                  "rows": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "rowValue": {
                          "type": "string"
                        },
                        "rowLabel": {
                          "type": "string"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "cells": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "columnValue": {
                                "type": "string"
                              },
                              "columnLabel": {
                                "type": "string"
                              },
                              "count": {
                                "type": "integer",
                                "nullable": true
                              },
                              "percentage": {
                                "type": "number",
                                "nullable": true
                              },
                              "suppressed": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "columnValue",
                              "columnLabel",
                              "count",
                              "percentage",
                              "suppressed"
                            ]
                          }
                        }
                      },
                      "required": [
                        "rowValue",
                        "rowLabel",
                        "total",
                        "cells"
                      ]
                    }
                  }
                },
                "required": [
                  "version",
                  "rowField",
                  "columnField",
                  "rows"
                ],
                "nullable": true
              },
              "privacySuppressed": {
                "type": "boolean"
              }
            },
            "required": [
              "range",
              "responseCount",
              "versions",
              "trend",
              "questions",
              "crossTab"
            ]
          }
        },
        "required": [
          "schema",
          "results"
        ]
      }
    }
  },
  "paths": {
    "/v1/forms/{formId}/schema": {
      "get": {
        "operationId": "schema",
        "tags": [
          "Survey results"
        ],
        "summary": "Read a published survey question contract",
        "description": "Growth or Scale, read_results permission, selected survey scope and published Results API opt-in required. Returns authorized private schema/aggregates, not raw submission rows or upload URLs. 120 requests/minute on Growth, 600 on Scale per key/form. Results queries use UTC from-inclusive/to-exclusive dates, maximum range 366 days. Cross-tabs require one version; filters and version comparisons are available on Growth and Scale; cross-tabs and research controls depend on Scale. Answer filters other than answered require nonempty values. POST query is read-only. Authorized aggregate queries may reuse a private 30-second cached result.",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "x-required-permission": "read_results",
        "parameters": [
          {
            "name": "formId",
            "in": "path",
            "required": true,
            "description": "Your selected published form or survey ID; use your portal contract, not the fictional examples.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          },
          {
            "name": "version",
            "in": "query",
            "required": false,
            "description": "Immutable published version; defaults to the credential's current published version. This endpoint is for survey result schemas, not form submission schemas.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Authorized immutable survey contract or aggregate report.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SurveySchema"
                }
              }
            }
          },
          "400": {
            "description": "invalid_request or invalid_json. Correct input before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "invalid_api_key: missing/invalid/revoked/expired key, permission, selected form, plan or published API opt-in. The API intentionally does not disclose which check failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "Feature or query unavailable for this workspace plan.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Published version or requested resource unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Authentication or per-key/form rate limit reached. Honor Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retrying."
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporary database/service interruption. Retry a submission with the same key, credential and body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/forms/{formId}/results/query": {
      "post": {
        "operationId": "results",
        "tags": [
          "Survey results"
        ],
        "summary": "Query aggregate survey results",
        "description": "Growth or Scale, read_results permission, selected survey scope and published Results API opt-in required. Returns authorized private schema/aggregates, not raw submission rows or upload URLs. 120 requests/minute on Growth, 600 on Scale per key/form. Results queries use UTC from-inclusive/to-exclusive dates, maximum range 366 days. Cross-tabs require one version; filters and version comparisons are available on Growth and Scale; cross-tabs and research controls depend on Scale. Answer filters other than answered require nonempty values. POST query is read-only. Authorized aggregate queries may reuse a private 30-second cached result.",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "x-required-permission": "read_results",
        "parameters": [
          {
            "name": "formId",
            "in": "path",
            "required": true,
            "description": "Your selected published form or survey ID; use your portal contract, not the fictional examples.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "from": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  },
                  "to": {
                    "type": "string",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                  },
                  "version": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "maximum": 9007199254740991
                  },
                  "questionIds": {
                    "maxItems": 100,
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 128
                    }
                  },
                  "filters": {
                    "type": "object",
                    "properties": {
                      "sources": {
                        "maxItems": 20,
                        "type": "array",
                        "items": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200
                        }
                      },
                      "campaigns": {
                        "maxItems": 20,
                        "type": "array",
                        "items": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200
                        }
                      },
                      "waves": {
                        "maxItems": 20,
                        "type": "array",
                        "items": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 200
                        }
                      },
                      "devices": {
                        "maxItems": 5,
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "desktop",
                            "mobile",
                            "tablet",
                            "unknown",
                            "api"
                          ]
                        }
                      },
                      "answers": {
                        "maxItems": 10,
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "fieldId": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 128
                            },
                            "operator": {
                              "type": "string",
                              "enum": [
                                "equals",
                                "in",
                                "answered"
                              ]
                            },
                            "values": {
                              "maxItems": 50,
                              "type": "array",
                              "items": {
                                "anyOf": [
                                  {
                                    "type": "string",
                                    "maxLength": 500
                                  },
                                  {
                                    "type": "number"
                                  },
                                  {
                                    "type": "boolean"
                                  }
                                ]
                              }
                            }
                          },
                          "required": [
                            "fieldId",
                            "operator"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "includeArchived": {
                        "default": true,
                        "type": "boolean"
                      },
                      "includeSpam": {
                        "default": false,
                        "type": "boolean"
                      }
                    },
                    "additionalProperties": false
                  },
                  "crossTab": {
                    "type": "object",
                    "properties": {
                      "rowFieldId": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128
                      },
                      "columnFieldId": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128
                      }
                    },
                    "required": [
                      "rowFieldId",
                      "columnFieldId"
                    ],
                    "additionalProperties": false
                  }
                },
                "additionalProperties": false
              },
              "example": {
                "version": 1,
                "questionIds": [
                  "replace-with-your-question-id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Authorized immutable survey contract or aggregate report.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SurveyResults"
                }
              }
            }
          },
          "400": {
            "description": "invalid_request or invalid_json. Correct input before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "invalid_api_key: missing/invalid/revoked/expired key, permission, selected form, plan or published API opt-in. The API intentionally does not disclose which check failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "Feature or query unavailable for this workspace plan.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Published version or requested resource unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "unsupported_media_type: use Content-Type: application/json.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Authentication or per-key/form rate limit reached. Honor Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retrying."
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporary database/service interruption. Retry a submission with the same key, credential and body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/forms/{formId}/submissions": {
      "post": {
        "operationId": "submissions",
        "tags": [
          "Submissions"
        ],
        "summary": "Submit a real response",
        "description": "Growth or Scale, submissions permission, selected form scope and published API opt-in required. Every accepted request, including tests, consumes ordinary monthly response allowance and can trigger real notifications, webhooks and workflows. Get the exact published field/value map and JSON Schema from the form's API submission settings. formVersion is an optional guard. Files and honeypot answers are unsupported; required uploads and Stripe Checkout forms cannot use API v1. 60 requests/minute on Growth, 300 on Scale per key/form.",
        "security": [
          {
            "ApiKey": []
          }
        ],
        "x-required-permission": "submissions",
        "parameters": [
          {
            "name": "formId",
            "in": "path",
            "required": true,
            "description": "Your selected published form or survey ID; use your portal contract, not the fictional examples.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "Reuse only for the identical logical submission, credential and body. Rotating the key changes the retry namespace.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._:-]{8,128}$",
              "example": "request_example_001"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "answers": {
                    "type": "object",
                    "additionalProperties": {
                      "anyOf": [
                        {
                          "type": "string",
                          "maxLength": 20000
                        },
                        {
                          "type": "number"
                        },
                        {
                          "type": "boolean"
                        },
                        {
                          "type": "string",
                          "nullable": true,
                          "enum": [
                            null
                          ]
                        },
                        {
                          "maxItems": 100,
                          "type": "array",
                          "items": {
                            "type": "string",
                            "maxLength": 5000
                          }
                        },
                        {
                          "type": "object",
                          "additionalProperties": {}
                        }
                      ]
                    }
                  },
                  "formVersion": {
                    "type": "integer",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "maximum": 9007199254740991
                  },
                  "metadata": {
                    "type": "object",
                    "properties": {
                      "externalId": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 200
                      }
                    },
                    "additionalProperties": false
                  }
                },
                "required": [
                  "answers"
                ],
                "additionalProperties": false
              },
              "example": {
                "formVersion": 1,
                "answers": {
                  "replace-with-your-field-id": "replace-with-your-machine-value"
                },
                "metadata": {
                  "externalId": "example_record"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Identical replay: original receipt, no second response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmissionReceipt"
                }
              }
            },
            "headers": {
              "Idempotent-Replayed": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "true"
                  ]
                }
              }
            }
          },
          "201": {
            "description": "New response accepted. Example contract and outcome vary by form.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmissionReceipt"
                }
              }
            }
          },
          "400": {
            "description": "invalid_request or invalid_json. Correct input before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "invalid_api_key: missing/invalid/revoked/expired key, permission, selected form, plan or published API opt-in. The API intentionally does not disclose which check failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "collection_quota_exceeded. Accepted responses have reached the workspace monthly allowance.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Feature or query unavailable for this workspace plan.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Published version or requested resource unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "form_version_mismatch, idempotency_conflict, idempotency_in_progress or api_submission_unsupported. Retry only the identical in-progress request with the same credential/key/body; honor Retry-After. Otherwise review the contract/input.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "survey_expired: collection window has closed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "payload_too_large: JSON request exceeds 768 KB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "unsupported_media_type: use Content-Type: application/json.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "validation_failed: correct field values; do not retry unchanged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Authentication or per-key/form rate limit reached. Honor Retry-After.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                },
                "description": "Seconds until retrying."
              }
            }
          },
          "500": {
            "description": "Unexpected server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporary database/service interruption. Retry a submission with the same key, credential and body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  }
}