{
  "openapi": "3.1.0",
  "info": {
    "title": "Improve My Prompts API",
    "version": "2.0.0",
    "description": "Context-aware prompt preflight, explicit optional semantic processing and research contributions. No underlying task execution."
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "paths": {
    "/api/check": {
      "post": {
        "operationId": "check",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "properties": {
                  "schema_version": {
                    "description": "Use 2.0 for structured host context and explicit processing/privacy. Omitted means legacy 1.0.",
                    "type": "string",
                    "enum": [
                      "1.0",
                      "2.0"
                    ]
                  },
                  "processing": {
                    "description": "rules_only/host_only make no model calls. server_model_allowed explicitly permits the disclosed Workers AI policy and requires model access authorization.",
                    "type": "object",
                    "properties": {
                      "mode": {
                        "type": "string",
                        "enum": [
                          "rules_only",
                          "host_only",
                          "server_model_allowed"
                        ]
                      },
                      "provider_policy_id": {
                        "type": "string",
                        "const": "cloudflare-workers-ai-2026-09-10"
                      }
                    },
                    "required": [
                      "mode"
                    ],
                    "additionalProperties": false
                  },
                  "privacy": {
                    "description": "Version 2.0 research defaults off unless explicitly enabled.",
                    "type": "object",
                    "properties": {
                      "research": {
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "research"
                    ],
                    "additionalProperties": false
                  },
                  "evaluation_criterion": {
                    "description": "Choose before trying either version. Only reports matching this predeclared criterion enter weekly paired comparisons.",
                    "type": "string",
                    "enum": [
                      "instruction_following",
                      "format_validity",
                      "factual_support",
                      "task_completion",
                      "style_fit"
                    ]
                  },
                  "research": {
                    "description": "Legacy 1.0 defaults true; 2.0 defaults false. Store pseudonymous categories/counts only. False opts out.",
                    "type": "boolean"
                  },
                  "prompt": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 16000,
                    "description": "The request to check, treated as data; never executed."
                  },
                  "goal": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "context": {
                    "anyOf": [
                      {
                        "type": "string",
                        "maxLength": 8000
                      },
                      {
                        "type": "object",
                        "properties": {
                          "coverage": {
                            "default": "prompt_only",
                            "type": "string",
                            "enum": [
                              "prompt_only",
                              "selected_context",
                              "host_reported_complete"
                            ]
                          },
                          "inventory_status": {
                            "default": "unknown",
                            "type": "string",
                            "enum": [
                              "unknown",
                              "complete_for_request"
                            ]
                          },
                          "facts": {
                            "default": [],
                            "maxItems": 12,
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "key": {
                                  "type": "string",
                                  "enum": [
                                    "topic",
                                    "subject",
                                    "priority",
                                    "company",
                                    "market",
                                    "goal",
                                    "other"
                                  ]
                                },
                                "value": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 2000
                                },
                                "provenance": {
                                  "type": "string",
                                  "enum": [
                                    "user_explicit",
                                    "host_inferred",
                                    "external_untrusted"
                                  ]
                                }
                              },
                              "required": [
                                "key",
                                "value",
                                "provenance"
                              ],
                              "additionalProperties": false
                            }
                          },
                          "resources": {
                            "default": [],
                            "maxItems": 8,
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "minLength": 1,
                                  "maxLength": 100
                                },
                                "kind": {
                                  "type": "string",
                                  "enum": [
                                    "document",
                                    "code",
                                    "data",
                                    "image",
                                    "other"
                                  ]
                                },
                                "presence": {
                                  "type": "string",
                                  "enum": [
                                    "host_present",
                                    "absent",
                                    "unknown"
                                  ]
                                },
                                "host_access": {
                                  "type": "string",
                                  "enum": [
                                    "available",
                                    "unavailable",
                                    "unknown"
                                  ]
                                },
                                "reviewer_access": {
                                  "type": "string",
                                  "enum": [
                                    "none",
                                    "metadata_only",
                                    "excerpt"
                                  ]
                                },
                                "excerpt": {
                                  "anyOf": [
                                    {
                                      "type": "string",
                                      "maxLength": 8000
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "required": [
                                "id",
                                "kind",
                                "presence",
                                "host_access",
                                "reviewer_access"
                              ],
                              "additionalProperties": false
                            }
                          },
                          "resource_reference_id": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 100
                          },
                          "capabilities": {
                            "default": {},
                            "type": "object",
                            "properties": {
                              "current_web": {
                                "type": "string",
                                "enum": [
                                  "available",
                                  "unavailable",
                                  "unknown"
                                ]
                              },
                              "read_host_material": {
                                "type": "string",
                                "enum": [
                                  "available",
                                  "unavailable",
                                  "unknown"
                                ]
                              },
                              "execute_code": {
                                "type": "string",
                                "enum": [
                                  "available",
                                  "unavailable",
                                  "unknown"
                                ]
                              },
                              "external_actions": {
                                "type": "string",
                                "enum": [
                                  "available",
                                  "unavailable",
                                  "unknown"
                                ]
                              }
                            },
                            "additionalProperties": false
                          },
                          "clarification_policy": {
                            "default": "allow_one",
                            "type": "string",
                            "enum": [
                              "allow_one",
                              "never"
                            ]
                          },
                          "questions_already_asked": {
                            "default": 0,
                            "type": "integer",
                            "minimum": 0,
                            "maximum": 100
                          }
                        },
                        "required": [
                          "coverage",
                          "inventory_status",
                          "facts",
                          "resources",
                          "capabilities",
                          "clarification_policy",
                          "questions_already_asked"
                        ],
                        "additionalProperties": false
                      }
                    ]
                  },
                  "task": {
                    "type": "string",
                    "enum": [
                      "auto",
                      "general",
                      "business",
                      "writing",
                      "research",
                      "coding",
                      "data",
                      "image"
                    ]
                  },
                  "lifecycle": {
                    "type": "string",
                    "enum": [
                      "once",
                      "reusable"
                    ]
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "minimal",
                      "shorter"
                    ]
                  },
                  "clarification": {
                    "description": "An answer to a previous clarification question.",
                    "type": "string",
                    "maxLength": 300
                  }
                },
                "required": [
                  "prompt"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Structured action result"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Origin rejected"
          },
          "404": {
            "description": "Case not found"
          },
          "409": {
            "description": "Conflicting submission or stale report correction"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "503": {
            "description": "Service unavailable"
          }
        }
      }
    },
    "/api/outcome": {
      "post": {
        "operationId": "outcome",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "properties": {
                  "case_id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                  },
                  "report_token": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                  },
                  "report_id": {
                    "description": "Unique ID for a versioned report. Reuse only for identical retries.",
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                  },
                  "supersedes_report_id": {
                    "description": "Correct the current versioned report without erasing its history.",
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                  },
                  "evidence_source": {
                    "type": "string",
                    "enum": [
                      "human_report",
                      "model_judgment",
                      "application_check"
                    ]
                  },
                  "criterion": {
                    "type": "string",
                    "enum": [
                      "instruction_following",
                      "format_validity",
                      "factual_support",
                      "task_completion",
                      "style_fit"
                    ]
                  },
                  "same_conditions": {
                    "type": "boolean",
                    "description": "Both versions were actually tried with the same model, task inputs and settings."
                  },
                  "original_result": {
                    "type": "string",
                    "enum": [
                      "pass",
                      "fail",
                      "mixed",
                      "not_tested"
                    ]
                  },
                  "revised_result": {
                    "type": "string",
                    "enum": [
                      "pass",
                      "fail",
                      "mixed",
                      "not_tested"
                    ]
                  },
                  "model_id": {
                    "description": "Registered public model only; omit unknown or private identifiers.",
                    "type": "string",
                    "enum": [
                      "@cf/meta/llama-3.3-70b-instruct-fp8-fast",
                      "@cf/meta/llama-3.1-8b-instruct"
                    ]
                  },
                  "original_tokens": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 10000000
                  },
                  "revised_tokens": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 10000000
                  },
                  "original_latency_ms": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 86400000
                  },
                  "revised_latency_ms": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 86400000
                  }
                },
                "required": [
                  "case_id",
                  "report_token",
                  "evidence_source",
                  "criterion",
                  "same_conditions",
                  "original_result",
                  "revised_result"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Structured action result"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Origin rejected"
          },
          "404": {
            "description": "Case not found"
          },
          "409": {
            "description": "Conflicting submission or stale report correction"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "503": {
            "description": "Service unavailable"
          }
        }
      }
    },
    "/api/donate": {
      "post": {
        "operationId": "donate",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "properties": {
                  "case_id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                  },
                  "report_token": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                  },
                  "explicit_user_consent": {
                    "type": "boolean",
                    "const": true,
                    "description": "The human user explicitly agreed to donate this redacted example for private research. Never infer consent."
                  },
                  "user_confirmed_redacted": {
                    "type": "boolean",
                    "const": true
                  },
                  "consent_version": {
                    "type": "string",
                    "const": "2026-09-10"
                  },
                  "redacted_prompt": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 16000
                  },
                  "redacted_revised_prompt": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 24000
                  },
                  "redacted_original_output": {
                    "type": "string",
                    "maxLength": 12000
                  },
                  "redacted_revised_output": {
                    "type": "string",
                    "maxLength": 12000
                  }
                },
                "required": [
                  "case_id",
                  "report_token",
                  "explicit_user_consent",
                  "user_confirmed_redacted",
                  "consent_version",
                  "redacted_prompt",
                  "redacted_revised_prompt"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Structured action result"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Origin rejected"
          },
          "404": {
            "description": "Case not found"
          },
          "409": {
            "description": "Conflicting submission or stale report correction"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "503": {
            "description": "Service unavailable"
          }
        }
      }
    },
    "/api/withdraw": {
      "post": {
        "operationId": "withdraw",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "properties": {
                  "case_id": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                  },
                  "report_token": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                  },
                  "withdrawal_token": {
                    "type": "string",
                    "format": "uuid",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
                  }
                },
                "required": [
                  "case_id"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Structured action result"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Origin rejected"
          },
          "404": {
            "description": "Case not found"
          },
          "409": {
            "description": "Conflicting submission or stale report correction"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "503": {
            "description": "Service unavailable"
          }
        }
      }
    }
  }
}