{
  "openapi": "3.0.3",
  "info": {
    "title": "Emdee API",
    "description": "REST API for managing Emdee documents. Create, read, list and update markdown documents in your workspace from any HTTP client.",
    "version": "1.0.0",
    "contact": { "name": "Emdee API Support" }
  },
  "servers": [
    {
      "url": "https://api.tryaware.ai/functions/v1/emdee-public-api",
      "description": "Production"
    }
  ],
  "security": [{ "BearerAuth": [] }],
  "tags": [
    { "name": "Documents", "description": "Read and write markdown documents." }
  ],
  "paths": {
    "/docs": {
      "get": {
        "operationId": "listDocs",
        "summary": "List documents",
        "description": "List documents in the workspace tied to your API key. Returns the most recently updated documents first. Markdown and HTML are omitted for brevity — fetch a single doc to retrieve content.",
        "tags": ["Documents"],
        "parameters": [
          {
            "name": "folder_id",
            "in": "query",
            "required": false,
            "description": "Filter by folder UUID.",
            "schema": { "type": "string", "format": "uuid" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of documents to return.",
            "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }
          }
        ],
        "responses": {
          "200": {
            "description": "List of documents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["docs"],
                  "properties": {
                    "docs": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/DocSummary" }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      },
      "post": {
        "operationId": "createDoc",
        "summary": "Create a document",
        "description": "Create a new document in the caller's workspace. All fields are optional — an untitled, empty doc will be created if no body is provided.",
        "tags": ["Documents"],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/DocCreate" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Doc" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/docs/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Document UUID.",
          "schema": { "type": "string", "format": "uuid" }
        }
      ],
      "get": {
        "operationId": "getDoc",
        "summary": "Read a document",
        "description": "Read a single document including its markdown body and rendered HTML.",
        "tags": ["Documents"],
        "responses": {
          "200": {
            "description": "The document",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Doc" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      },
      "patch": {
        "operationId": "updateDoc",
        "summary": "Update a document",
        "description": "Update a document's title and/or markdown body. At least one field is required. Writes to `markdown` replace `latest_markdown`; the next time the document is opened in the editor, the CRDT will re-seed from this value if it has no newer edits.",
        "tags": ["Documents"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/DocUpdate" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated document",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Doc" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key issued from Emdee → Settings → API keys. Keys are prefixed `emdee_` and validated by SHA-256 hash."
      }
    },
    "schemas": {
      "DocSummary": {
        "type": "object",
        "required": ["id", "title", "folder_id", "created_at", "updated_at", "created_by"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "title": { "type": "string" },
          "folder_id": { "type": "string", "format": "uuid", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" },
          "created_by": { "type": "string", "format": "uuid" }
        }
      },
      "Doc": {
        "allOf": [
          { "$ref": "#/components/schemas/DocSummary" },
          {
            "type": "object",
            "required": ["markdown", "html"],
            "properties": {
              "markdown": { "type": "string" },
              "html": { "type": "string", "description": "Server-rendered HTML from the markdown body." }
            }
          }
        ]
      },
      "DocCreate": {
        "type": "object",
        "properties": {
          "title": { "type": "string", "maxLength": 500, "default": "Untitled" },
          "markdown": { "type": "string" },
          "folder_id": { "type": "string", "format": "uuid", "nullable": true }
        }
      },
      "DocUpdate": {
        "type": "object",
        "minProperties": 1,
        "properties": {
          "title": { "type": "string", "maxLength": 500 },
          "markdown": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" }
            }
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request body or parameters.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Forbidden": {
        "description": "API key has expired or has no workspace.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "NotFound": {
        "description": "Document not found in this workspace.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "InternalError": {
        "description": "Unexpected server error.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  }
}