{
  "openapi": "3.1.0",
  "info": {
    "title": "See the Field Content Report API",
    "version": "1.0.0",
    "summary": "Submit a report about incorrect or unclear learning content in the See the Field iOS app.",
    "description": "A single unauthenticated endpoint used by the See the Field iOS app to report questions, concept cards, or animations that appear incorrect, unclear, or mislabelled. Reports are written to a moderation queue and reviewed by hand.\n\nThis is the only public HTTP API operated by See the Field. There is no user-facing API, no authentication, and no read access — the app stores all user data locally on device.",
    "contact": {
      "name": "See the Field Support",
      "email": "support@seethefield.app",
      "url": "https://seethefield.app/support.html"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://seethefield.app/terms.html"
    }
  },
  "servers": [
    {
      "url": "https://famous-goshawk-386.convex.site",
      "description": "Production (Convex HTTP actions)"
    }
  ],
  "externalDocs": {
    "description": "Human-readable documentation",
    "url": "https://seethefield.app/api/"
  },
  "paths": {
    "/api/content-report": {
      "post": {
        "operationId": "submitContentReport",
        "summary": "Submit a content report",
        "description": "Records a report about a piece of learning content. No authentication is required and no response body is returned on success.\n\nField names may be supplied in either snake_case or camelCase; snake_case takes precedence when both are present.",
        "tags": ["Content reports"],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ContentReport" },
              "examples": {
                "wrongAnswer": {
                  "summary": "A quiz question with an answer the user believes is wrong",
                  "value": {
                    "content_type": "question",
                    "question_id": "ff-cover3-004",
                    "game_mode": "formation_flash",
                    "surface": "quiz",
                    "reason": "incorrect_answer",
                    "comment": "The listed formation is Trips Right, not Bunch Right.",
                    "app_version": "1.0.5",
                    "device_model": "iPhone15,3",
                    "os_version": "18.2"
                  }
                },
                "unclearCard": {
                  "summary": "A concept card that reads ambiguously",
                  "value": {
                    "content_type": "concept_card",
                    "concept_card_id": "l2-route-tree-card-3",
                    "concept_id": "l2-route-tree",
                    "surface": "learn",
                    "reason": "unclear_wording"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Report accepted and queued for review. No response body."
          },
          "400": {
            "description": "The request body was not valid JSON, or a required field was missing or not a string.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" },
                "examples": {
                  "missingFields": {
                    "value": {
                      "error": "Missing required fields: content_type, surface, reason"
                    }
                  },
                  "invalidJson": { "value": { "error": "Invalid JSON" } }
                }
              }
            }
          },
          "500": {
            "description": "The report could not be stored.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" },
                "examples": {
                  "serverError": { "value": { "error": "Internal server error" } }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ContentReport": {
        "type": "object",
        "description": "A report about a single piece of learning content. Every property is a string. Empty strings are treated as absent for optional fields, and as missing for required fields.",
        "required": ["content_type", "surface", "reason"],
        "properties": {
          "content_type": {
            "type": "string",
            "description": "What kind of content is being reported.",
            "examples": ["question", "concept_card", "animation", "glossary"]
          },
          "surface": {
            "type": "string",
            "description": "Where in the app the report was raised.",
            "examples": ["quiz", "practice", "learn", "film_room"]
          },
          "reason": {
            "type": "string",
            "description": "Why the content is being reported.",
            "examples": [
              "incorrect_answer",
              "unclear_wording",
              "wrong_diagram",
              "typo",
              "other"
            ]
          },
          "question_id": {
            "type": "string",
            "description": "Identifier of the reported quiz question, when content_type is a question."
          },
          "concept_card_id": {
            "type": "string",
            "description": "Identifier of the reported concept card, when content_type is a concept card."
          },
          "concept_id": {
            "type": "string",
            "description": "Identifier of the curriculum concept the content belongs to."
          },
          "game_mode": {
            "type": "string",
            "description": "The game mode the report was raised from.",
            "examples": [
              "formation_flash",
              "coverage_read",
              "play_call",
              "counter_pick",
              "film_room",
              "daily_drive"
            ]
          },
          "comment": {
            "type": "string",
            "description": "Free-text detail written by the user."
          },
          "app_version": {
            "type": "string",
            "description": "Version of the iOS app that submitted the report.",
            "examples": ["1.0.5"]
          },
          "device_model": {
            "type": "string",
            "description": "Device model identifier.",
            "examples": ["iPhone15,3"]
          },
          "os_version": {
            "type": "string",
            "description": "iOS version.",
            "examples": ["18.2"]
          }
        },
        "additionalProperties": false
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable description of what went wrong."
          }
        }
      }
    }
  }
}