{
  "openapi": "3.1.0",
  "info": {
    "title": "TextPreflight API",
    "version": "0.1.0",
    "summary": "Provider-neutral SMS encoding, segmentation, Unicode and cost preflight.",
    "description": "Analyze and optimize SMS copy, simulate template samples and estimate campaign billable segments. Message bodies are processed in memory and are not stored by the application."
  },
  "servers": [{ "url": "https://textpreflight.kadircoteli.workers.dev", "description": "Production" }],
  "tags": [{ "name": "SMS" }, { "name": "Templates" }, { "name": "Campaigns" }],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Service health",
        "responses": { "200": { "description": "Healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } }
      }
    },
    "/api/v1/sms/analyze": {
      "post": {
        "tags": ["SMS"], "operationId": "analyzeSms", "summary": "Analyze one SMS message",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyzeRequest" }, "examples": { "basic": { "value": { "text": "Your order is ready.", "recipients": 10000, "unitPrice": 0.0075, "currency": "USD" } } } } } },
        "responses": { "200": { "description": "Analysis completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyzeResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/api/v1/sms/optimize": {
      "post": {
        "tags": ["SMS"], "operationId": "optimizeSms", "summary": "Apply safe, explainable typography fixes",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptimizeRequest" } } } },
        "responses": { "200": { "description": "Optimization completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptimizeResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/api/v1/template/simulate": {
      "post": {
        "tags": ["Templates"], "operationId": "simulateTemplate", "summary": "Analyze template sample combinations",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRequest" } } } },
        "responses": { "200": { "description": "Simulation completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    },
    "/api/v1/campaign/estimate": {
      "post": {
        "tags": ["Campaigns"], "operationId": "estimateCampaign", "summary": "Forecast campaign segments and cost",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignRequest" } } } },
        "responses": { "200": { "description": "Estimate completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" } } } }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }
      }
    }
  },
  "components": {
    "responses": {
      "ValidationError": { "description": "Input validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
      "RateLimited": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
    },
    "schemas": {
      "Profile": { "type": "string", "enum": ["standard", "twilio-tollfree-us-ca"], "default": "standard" },
      "CommonOptions": {
        "type": "object",
        "properties": {
          "profile": { "$ref": "#/components/schemas/Profile" },
          "unitPrice": { "type": "number", "minimum": 0, "maximum": 10000, "description": "Price per billable segment." },
          "recipients": { "type": "integer", "minimum": 1, "maximum": 100000000, "default": 1 },
          "currency": { "type": "string", "default": "USD", "maxLength": 10000 }
        }
      },
      "AnalyzeRequest": {
        "allOf": [{ "$ref": "#/components/schemas/CommonOptions" }, { "type": "object", "required": ["text"], "properties": { "text": { "type": "string", "maxLength": 10000 } } }]
      },
      "OptimizeRequest": {
        "allOf": [{ "$ref": "#/components/schemas/AnalyzeRequest" }, { "type": "object", "properties": { "removeInvisible": { "type": "boolean", "default": false } } }]
      },
      "TemplateRequest": {
        "allOf": [{ "$ref": "#/components/schemas/CommonOptions" }, { "type": "object", "required": ["template", "variables"], "properties": { "template": { "type": "string", "maxLength": 5000, "example": "Hi {{name}}, your code is {{code}}." }, "variables": { "type": "object", "additionalProperties": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "oneOf": [{ "type": "string", "maxLength": 500 }, { "type": "number" }] } } } } }]
      },
      "CampaignRequest": {
        "type": "object", "required": ["messages"], "properties": { "profile": { "$ref": "#/components/schemas/Profile" }, "unitPrice": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "default": "USD" }, "messages": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "required": ["text"], "properties": { "text": { "type": "string", "maxLength": 10000 }, "recipients": { "type": "integer", "minimum": 1, "maximum": 100000000, "default": 1 } } } } }
      },
      "Cost": { "type": ["object", "null"], "properties": { "currency": { "type": "string" }, "unitPrice": { "type": "number" }, "recipients": { "type": "integer" }, "billableSegments": { "type": "integer" }, "total": { "type": "number" } } },
      "Finding": { "type": "object", "additionalProperties": true, "properties": { "type": { "type": "string" }, "severity": { "type": "string" }, "index": { "type": "integer" }, "character": { "type": "string" }, "codePoint": { "type": "string" }, "message": { "type": "string" } } },
      "Analysis": {
        "type": "object", "required": ["encoding", "profile", "length", "segments", "characters", "unicode"], "properties": {
          "encoding": { "type": "string", "enum": ["GSM-7", "UCS-2"] },
          "profile": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" } } },
          "length": { "type": "object", "properties": { "codePoints": { "type": "integer" }, "utf16CodeUnits": { "type": "integer" }, "encodingUnits": { "type": "integer" } } },
          "segments": { "type": "object", "properties": { "count": { "type": "integer" }, "singlePartCapacity": { "type": "integer" }, "multipartCapacity": { "type": "integer" }, "activePartCapacity": { "type": "integer" }, "remainingInFinalPart": { "type": "integer" }, "billable": { "type": "integer" } } },
          "characters": { "type": "object", "properties": { "nonGsmCount": { "type": "integer" }, "nonGsm": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "extendedCount": { "type": "integer" }, "extended": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } },
          "unicode": { "type": "object", "properties": { "riskLevel": { "type": "string", "enum": ["none", "low", "medium", "high"] }, "scripts": { "type": "array", "items": { "type": "string" } }, "mixedScripts": { "type": "boolean" }, "findingCount": { "type": "integer" }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" } } } },
          "parts": { "type": ["array", "null"], "items": { "type": "object", "properties": { "index": { "type": "integer" }, "body": { "type": "string" }, "units": { "type": "integer" }, "capacity": { "type": "integer" } } } },
          "estimatedCost": { "$ref": "#/components/schemas/Cost" }
        }
      },
      "SuccessMeta": { "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid" }, "version": { "type": "string", "example": "2026-09-02" } } },
      "AnalyzeResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Analysis" }, "meta": { "$ref": "#/components/schemas/SuccessMeta" } } },
      "OptimizeResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "changed": { "type": "boolean" }, "optimizedText": { "type": "string" }, "replacements": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "before": { "$ref": "#/components/schemas/Analysis" }, "after": { "$ref": "#/components/schemas/Analysis" }, "savings": { "type": "object", "additionalProperties": true } } }, "meta": { "$ref": "#/components/schemas/SuccessMeta" } } },
      "TemplateResponse": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/SuccessMeta" } } },
      "CampaignResponse": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true }, "meta": { "$ref": "#/components/schemas/SuccessMeta" } } },
      "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "required": ["code", "message", "requestId"], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" }, "details": { "type": "object", "additionalProperties": true } } } } },
      "HealthResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "const": "ok" }, "service": { "const": "textpreflight" }, "version": { "type": "string" }, "privacy": { "type": "string" } } } } }
    }
  }
}