{
  "openapi": "3.1.0",
  "info": {
    "title": "PromptingEasy Free Prompt Generator API",
    "version": "1.0.0",
    "description": "Free, account-free, side-effect-free prompt composition for all active PromptingEasy Advanced generators. This service builds prompt text, not AI responses. No payment, API keys, AI-inference calls, or external message sending.",
    "termsOfService": "https://promptingeasy.com/agents/"
  },
  "servers": [
    {
      "url": "https://promptingeasy.com"
    }
  ],
  "externalDocs": {
    "url": "https://promptingeasy.com/agents/",
    "description": "Usage, security, privacy and AI-client instructions"
  },
  "tags": [
    {
      "name": "Prompt generators",
      "description": "Only active, published generators are exposed."
    }
  ],
  "paths": {
    "/api/v1/generators": {
      "get": {
        "tags": [
          "Prompt generators"
        ],
        "operationId": "listGenerators",
        "summary": "List all free active generators and supported languages",
        "parameters": [
          {
            "$ref": "#/components/parameters/locale"
          }
        ],
        "responses": {
          "200": {
            "description": "Directory of active generators.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GeneratorList"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/v1/generators/{id}": {
      "get": {
        "tags": [
          "Prompt generators"
        ],
        "operationId": "getGeneratorDetails",
        "summary": "Get field options and custom or multi-select capabilities for a generator",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/GeneratorId"
            }
          },
          {
            "$ref": "#/components/parameters/locale"
          }
        ],
        "responses": {
          "200": {
            "description": "Field names, labels, published choices, custom-text and multiple-selection flags, and requirements.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/api/v1/prompts": {
      "post": {
        "tags": [
          "Prompt generators"
        ],
        "operationId": "generatePrompt",
        "summary": "Compose the same Advanced prompt as the browser generator",
        "description": "Use getGeneratorDetails to learn field names, option values, customAllowed flags and multiple flags. Returns a prompt; it does not execute AI inference, send text to ChatGPT or copy to a clipboard. The copyPayload field matches a newly generated browser Step-4 preview; human-edited previews are not accessible through the API.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromptRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Composed prompt and the exact content for the initial Step-4 Copy button.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PromptResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "405": {
            "description": "Unsupported method."
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "locale": {
        "name": "locale",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "default": "en"
        },
        "description": "Published language code from GET /api/v1/generators."
      }
    },
    "schemas": {
      "GeneratorId": {
        "type": "string",
        "enum": [
          "universal",
          "job-cv",
          "writing-email",
          "translation-language",
          "student-learning",
          "cooking-meal-plan",
          "small-business",
          "travel-city-trip",
          "money-saving",
          "ai-image"
        ]
      },
      "GeneratorList": {
        "type": "object",
        "required": [
          "service",
          "free",
          "noAccountRequired",
          "locale",
          "locales",
          "generators"
        ],
        "properties": {
          "service": {
            "type": "string"
          },
          "free": {
            "const": true
          },
          "noAccountRequired": {
            "const": true
          },
          "locale": {
            "type": "string"
          },
          "locales": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "generators": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "url",
                "details"
              ],
              "properties": {
                "id": {
                  "$ref": "#/components/schemas/GeneratorId"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "details": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          }
        }
      },
      "PromptRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "generator",
          "fields"
        ],
        "properties": {
          "generator": {
            "$ref": "#/components/schemas/GeneratorId"
          },
          "locale": {
            "type": "string",
            "default": "en",
            "description": "Published locale code."
          },
          "fields": {
            "type": "object",
            "maxProperties": 25,
            "description": "Keys are published generator fields from GET /api/v1/generators/{id}. Use a dropdown option or custom text when customAllowed=true; multiple=true fields accept 1–12 selections (at most one custom item).",
            "additionalProperties": {
              "oneOf": [
                {
                  "type": "string",
                  "maxLength": 600
                },
                {
                  "type": "array",
                  "minItems": 1,
                  "maxItems": 12,
                  "uniqueItems": true,
                  "items": {
                    "type": "string",
                    "maxLength": 600
                  }
                }
              ]
            }
          },
          "image_subject": {
            "type": "string",
            "maxLength": 600,
            "description": "Required for ai-image only."
          },
          "source_text": {
            "type": "string",
            "maxLength": 5000,
            "description": "Optional extra facts such as destination, original appointment or proposed date. Appended to copyPayload; no AI model is called."
          },
          "presentation": {
            "type": "string",
            "enum": ["classic", "guided"],
            "default": "classic",
            "description": "classic: initial browser Step-4 output (all locales); guided: localized natural-language instructions and missing-information placeholders (all 22 locales). Image prompts remain classic."
          }
        }
      },
      "PromptResponse": {
        "type": "object",
        "required": [
          "generator",
          "locale",
          "prompt",
          "sourceIncluded",
          "copyPayload",
          "note"
        ],
        "properties": {
          "generator": {
            "$ref": "#/components/schemas/GeneratorId"
          },
          "locale": {
            "type": "string"
          },
          "prompt": {
            "type": "string"
          },
          "sourceIncluded": {
            "type": "boolean"
          },
          "copyPayload": {
            "type": "string"
          },
          "note": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Malformed JSON, unsupported locale or generator, unknown field, invalid selection or oversized input.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}
