{
  "openapi": "3.1.0",
  "info": {
    "title": "Bridgify draft authoring",
    "version": "1.0.0",
    "description": "Draft authoring API. Requires a provisioned, non-expired scoped bearer token. Creates drafts only; never publishes."
  },
  "components": {
    "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer" } }
  },
  "security": [{ "apiKey": [] }],
  "paths": {
    "/api/v1/drafts": {
      "post": {
        "operationId": "createUpdateDraft",
        "description": "Requires drafts:create. Reuse Idempotency-Key only with the same payload. Never publishes.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 128 }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": ["title", "intro", "body"],
                "properties": {
                  "title": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "intro": { "type": "string", "maxLength": 2000 },
                  "body": { "type": "string", "maxLength": 20000 },
                  "releaseDate": { "type": "string", "format": "date" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "New draft",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["id", "revision", "status"],
                  "properties": {
                    "id": { "type": "string", "format": "uuid" },
                    "revision": { "type": "integer" },
                    "status": { "const": "draft" }
                  }
                }
              }
            }
          },
          "200": { "description": "Same draft returned on retry" },
          "400": { "description": "Invalid input" },
          "401": { "description": "Invalid or expired token" },
          "403": { "description": "Scope denied" },
          "409": { "description": "Idempotency conflict" },
          "503": { "description": "Service unavailable" }
        }
      }
    }
  }
}
