{
  "openapi": "3.0.3",
  "info": {
    "title": "Docs API",
    "version": "1.0.0",
    "description": "API reference for Docs document, PDF, conversion, search, sync, and review workflows."
  },
  "servers": [
    {
      "url": "https://d0cs.app/api",
      "description": "Docs API"
    }
  ],
  "tags": [
    {
      "name": "Documents",
      "description": "Import, organize, and update documents."
    },
    {
      "name": "PDF Tools",
      "description": "Run PDF edit, merge, split, extract, compress, and protection jobs."
    },
    {
      "name": "Search",
      "description": "Search extracted text, metadata, tags, and AI-generated notes."
    },
    {
      "name": "Review Links",
      "description": "Create protected review links and collect private comments."
    },
    {
      "name": "Sync",
      "description": "Inspect encrypted backup and cross-device sync status."
    }
  ],
  "paths": {
    "/documents": {
      "get": {
        "tags": ["Documents"],
        "summary": "List documents",
        "operationId": "listDocuments",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional text, tag, folder, or file type filter."
          }
        ],
        "responses": {
          "200": {
            "description": "Documents matching the requested filter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentList"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Documents"],
        "summary": "Create a document import",
        "operationId": "createDocumentImport",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentImportRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Import accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          }
        }
      }
    },
    "/documents/{documentId}": {
      "get": {
        "tags": ["Documents"],
        "summary": "Get document metadata",
        "operationId": "getDocument",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentId"
          }
        ],
        "responses": {
          "200": {
            "description": "Document metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Document"
                }
              }
            }
          },
          "404": {
            "description": "Document not found."
          }
        }
      }
    },
    "/documents/{documentId}/pdf-jobs": {
      "post": {
        "tags": ["PDF Tools"],
        "summary": "Start a PDF tool job",
        "operationId": "createPdfToolJob",
        "parameters": [
          {
            "$ref": "#/components/parameters/DocumentId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PdfToolJobRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "PDF tool job accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          }
        }
      }
    },
    "/search": {
      "post": {
        "tags": ["Search"],
        "summary": "Search the document library",
        "operationId": "searchDocuments",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/review-links": {
      "post": {
        "tags": ["Review Links"],
        "summary": "Create a protected review link",
        "operationId": "createReviewLink",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReviewLinkRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Review link created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReviewLink"
                }
              }
            }
          }
        }
      }
    },
    "/sync/status": {
      "get": {
        "tags": ["Sync"],
        "summary": "Get encrypted sync status",
        "operationId": "getSyncStatus",
        "responses": {
          "200": {
            "description": "Current sync state.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SyncStatus"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "DocumentId": {
        "name": "documentId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Document identifier."
      }
    },
    "schemas": {
      "Document": {
        "type": "object",
        "required": ["id", "name", "type", "createdAt"],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": ["pdf", "docx", "xlsx", "pptx", "image", "text", "markdown", "other"]
          },
          "folder": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "DocumentList": {
        "type": "object",
        "required": ["items"],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Document"
            }
          }
        }
      },
      "DocumentImportRequest": {
        "type": "object",
        "required": ["source"],
        "properties": {
          "source": {
            "type": "string",
            "description": "File, folder, or remote import source."
          },
          "folder": {
            "type": "string"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "PdfToolJobRequest": {
        "type": "object",
        "required": ["action"],
        "properties": {
          "action": {
            "type": "string",
            "enum": ["merge", "split", "extract", "compress", "protect", "ocr", "convert"]
          },
          "pageRange": {
            "type": "string"
          },
          "passwordProtected": {
            "type": "boolean"
          }
        }
      },
      "SearchRequest": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": {
            "type": "string"
          },
          "includeAiNotes": {
            "type": "boolean",
            "default": true
          },
          "types": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": ["items"],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Document"
            }
          }
        }
      },
      "ReviewLinkRequest": {
        "type": "object",
        "required": ["documentIds"],
        "properties": {
          "documentIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "passwordProtected": {
            "type": "boolean"
          }
        }
      },
      "ReviewLink": {
        "type": "object",
        "required": ["id", "url"],
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SyncStatus": {
        "type": "object",
        "required": ["enabled", "state"],
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "state": {
            "type": "string",
            "enum": ["idle", "syncing", "paused", "failed"]
          },
          "lastSyncedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Job": {
        "type": "object",
        "required": ["id", "status"],
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["queued", "running", "completed", "failed"]
          }
        }
      }
    }
  }
}