{"openapi":"3.1.0","info":{"title":"Document Storage API - Public Endpoints","description":"Public API endpoints for document storage service","version":"v1.844.0"},"servers":[{"url":"https://api.stonal.io/document-storage"},{"url":"https://api.stonal-dev.io/document-storage"},{"url":"https://api.stonal-test.io/document-storage"},{"url":"https://api.stonal-staging.io/document-storage"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Files","description":"API for public file operations including upload functionality"},{"name":"Documents","description":"API for public document operations"},{"name":"Documentation Templates","description":"Public API for documentation templates"},{"name":"Documentations","description":"API for retrieving documentation information for assets"}],"paths":{"/v1/organizations/{organizationCode}/assets/{assetIdentifier}/documents/{documentIdentifier}/rename":{"put":{"tags":["Documents"],"summary":"Rename a document","description":"Changes the name of a document. Requires write authority on the asset. This endpoint is available for public use.","operationId":"renameDocument","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"},"example":"STONAL"},{"name":"assetIdentifier","in":"path","description":"Asset identifier (asset UID or ERP code)","required":true,"schema":{"type":"string"},"examples":{"uid":{"description":"uid","value":"123e4567-e89b-12d3-a456-426614174000"},"erp":{"description":"erp","value":"ERP-001"}}},{"name":"documentIdentifier","in":"path","description":"Document identifier","required":true,"schema":{"type":"string"},"example":"doc-456"},{"name":"name","in":"query","description":"New document name","required":true,"schema":{"type":"string"},"example":"Invoice-2023.pdf"}],"responses":{"200":{"description":"Document renamed successfully"},"400":{"description":"Invalid name format"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Document not found"}}}},"/v1/organizations/{organizationCode}/files/upload":{"post":{"tags":["Files"],"summary":"Upload a file","description":"Uploads a file with a JSON manifest. The manifest provides context for the upload, such as asset, documentation, linked assets, tags, properties, and destination folder.","operationId":"uploadFile","parameters":[{"name":"Manifest JSON Example","in":"query","description":"Structure of the manifest JSON file. All fields are optional. Add them based on your needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManifestView"}}}},{"name":"ticket","in":"query","description":"Optional single-use upload ticket issued by POST /v1/.../files/upload-ticket. When present, the permission check is skipped and the ticket is consumed before reading the file body — enabling large uploads without JWT expiry risk.","schema":{"type":"string"}},{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"},"example":"STONAL"}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UploadRequest"},"encoding":{"manifest":{"contentType":"application/json"},"file":{"contentType":"application/octet-stream"}}}},"required":true},"responses":{"200":{"description":"File successfully uploaded","headers":{"X-DOCUMENT-STORAGE-WARNING":{"description":"Optional warning codes related to non-blocking upload issues.","style":"simple"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileUploadedResponse"}}}},"400":{"description":"Bad request - Missing/invalid manifest fields"},"404":{"description":"Not Found - UID (asset, doc, or folder) not found"},"409":{"description":"Conflict - Specified asset & documentation aren't linked"},"422":{"description":"Unprocessable Entity - Template not found for asset"}}}},"/v1/organizations/{organizationCode}/documents/search":{"post":{"tags":["Documents"],"summary":"Search for documents","description":"Searches for documents based on provided filters with pagination and sorting options. This endpoint is available for public use.","operationId":"search","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"},"example":"org-123"},{"name":"pageNumber","in":"query","description":"Page number for pagination (starts at 1; 0 is accepted for backward compatibility)","required":false,"schema":{"type":"integer","format":"int32","default":1},"example":1},{"name":"pageSize","in":"query","description":"Page size for pagination","required":false,"schema":{"type":"integer","format":"int32","default":20},"example":20},{"name":"sortOrder","in":"query","description":"Sort order (asc or desc)","required":false,"schema":{"type":"string"},"example":"desc"},{"name":"columnToSort","in":"query","description":"Column to sort by","required":false,"schema":{"type":"string"},"example":"creationDate"},{"name":"updatedAfter","in":"query","description":"Filter documents updated during and after this date. Accepts an ISO-8601 date (YYYY-MM-DD) or date-time","required":false,"schema":{"type":"string"},"example":"2023-12-01"},{"name":"createdAfter","in":"query","description":"Filter documents created during and after this date. Accepts an ISO-8601 date (YYYY-MM-DD) or date-time","required":false,"schema":{"type":"string"},"example":"2023-12-01"},{"name":"afterId","in":"query","description":"Cursor for keyset pagination, ordered by id ascending; ignores pageNumber/columnToSort/sortOrder when present. Pass 0 to start a new cursor walk (omitting this parameter uses standard offset pagination and never returns a nextCursor); pass the previous response's nextCursor to fetch the following page.","required":false,"schema":{"type":"string"},"example":12345},{"name":"afterValue","in":"query","description":"Cursor value for update-date-ordered cursor pagination (used together with afterId and columnToSort=updateDate). ISO-8601 timestamp. Ignored unless columnToSort is exactly \"updateDate\"; omit to start a new update-date cursor walk.","required":false,"schema":{"type":"string"},"example":"2026-07-17T14:32:10.123456"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentSearchFilter"}}},"required":true},"responses":{"200":{"description":"Search completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageResultOfDocumentView"}}}},"400":{"description":"Invalid search parameters"}}}},"/v1/organizations/{organizationCode}/documents/documentation-tags":{"post":{"tags":["Documents"],"summary":"Add or remove documentation tags on documents","description":"Updates documentation tags on documents. Each item carries its asset scope in the request body, missing tags are created before assignment and the whole request is processed in one transaction.","operationId":"updateDocumentDocumentationTags","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"},"example":"STONAL"}],"requestBody":{"description":"Bulk documentation tag update request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDocumentDocumentationTagsRequest"},"examples":{"example":{"summary":"Add and remove tags","description":"example","value":{"items":[{"assetIdentifier":"asset-789","documentIdentifier":"doc-123","documentationIdentifier":"documentation-456","addTags":["LEASE","EDP 2024"],"removeTags":["ARCHIVE"]}]}}}}},"required":true},"responses":{"200":{"description":"Documentation tags updated successfully"},"400":{"description":"Invalid payload"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"One or more resources were not found"}}}},"/v1/organizations/{organizationCode}/templates":{"get":{"tags":["Documentation Templates"],"summary":"List documentation templates","description":"Returns the documentation templates available for an organization. A language parameter lets clients select the preferred locale for the name field.","operationId":"getTemplates","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"language","in":"query","description":"Preferred language","required":false,"schema":{"type":"string"},"example":"fr-FR"}],"responses":{"200":{"description":"Templates retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplatesListResponse"}}}},"403":{"description":"Forbidden"}}}},"/v1/organizations/{organizationCode}/templates/{templateId}":{"get":{"tags":["Documentation Templates"],"summary":"Get documentation template tree","description":"Returns the complete folder tree for a documentation template.","operationId":"getTemplate","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"templateId","in":"path","description":"Template identifier","required":true,"schema":{"type":"string"}},{"name":"language","in":"query","description":"Preferred language","required":false,"schema":{"type":"string"},"example":"fr-FR"}],"responses":{"200":{"description":"Template found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateDetailResponse"}}}},"404":{"description":"Template not found"}}}},"/v1/organizations/{organizationCode}/files/{documentIdentifier}":{"get":{"tags":["Files"],"summary":"Download a file","description":"Downloads a file by document identifier for a specific organization. The file will be returned as a binary stream.","operationId":"downloadFile","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"},"example":"STONAL"},{"name":"documentIdentifier","in":"path","description":"Document identifier","required":true,"schema":{"type":"string"},"example":"doc-456"}],"responses":{"200":{"description":"File successfully downloaded","content":{"application/octet-stream":{}}},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"File not found"}}}},"/v1/organizations/{organizationCode}/documents/{documentIdentifier}":{"get":{"tags":["Documents"],"summary":"Get a document by identifier","description":"Returns a document's metadata by identifier. The response always includes `identity` and `file`; every other section (`classification`, `tags`, `metadata`, `linkedAssets`, `stakeholders`, `lifecycle`, `references`) is included only when named in the `include` parameter. Pass `include=all` to get every section at once.","operationId":"getDocument","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"},"example":"STONAL"},{"name":"documentIdentifier","in":"path","description":"Document identifier","required":true,"schema":{"type":"string"},"example":"doc-456"},{"name":"include","in":"query","description":"Comma-separated list of sections to include in the response, or `all` for every section. Accepted values: classification, tags, metadata, linkedAssets, stakeholders, lifecycle, references, all. Omit to get only `identity` and `file`.","required":false,"schema":{"type":"string"},"example":"classification,references"}],"responses":{"200":{"description":"Document found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDetailResponse"}}}},"400":{"description":"Unknown value passed to `include`"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Document not found, or not accessible with the caller's authorization groups"}}},"delete":{"tags":["Documents"],"summary":"Delete a document","description":"Deletes a document by its identifier. This endpoint is available for public use.","operationId":"deleteDocument","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"},"example":"STONAL"},{"name":"documentIdentifier","in":"path","description":"Document identifier to delete","required":true,"schema":{"type":"string"},"example":"doc-456"},{"name":"documentationIdentifier","in":"query","description":"Optional documentation identifier. If provided, only the reference to that documentation is removed; the document is deleted once it has no remaining references. If omitted, the document is detached from every documentation it references and deleted.","required":false,"schema":{"type":"string"},"example":"documentation-789"}],"responses":{"200":{"description":"Document deleted successfully"},"403":{"description":"Forbidden - insufficient permissions"},"404":{"description":"Document not found"}}}},"/v1/organizations/{organizationCode}/documents/{documentIdentifier}/content":{"get":{"tags":["Documents"],"summary":"Show file content","description":"Show a file by its identifier. The file is identified by the document identifier.","operationId":"showFileContent","parameters":[{"name":"documentIdentifier","in":"path","description":"Document identifier","required":true,"schema":{"type":"string"},"example":"doc-456"},{"name":"organizationCode","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"File successfully downloaded","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Document not found"}}}},"/v1/organizations/{organizationCode}/assets/{assetId}/documentations":{"get":{"tags":["Documentations"],"summary":"Get documentations for an asset","description":"Retrieves all documentation entries associated with a specific asset identified by either assetUid or externalId","operationId":"getDocumentationsForAsset","parameters":[{"name":"organizationCode","in":"path","description":"Organization code","required":true,"schema":{"type":"string"}},{"name":"assetId","in":"path","description":"Asset identifier - either a UUID (123e4567-e89b-12d3-a456-426614174000) or an external ID (ERP:58654)","required":true,"schema":{"type":"string"},"example":"123e4567-e89b-12d3-a456-426614174000"}],"responses":{"200":{"description":"Successfully retrieved documentation entries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentationSimplifiedView"}}}},"400":{"description":"Bad request - invalid asset ID format","content":{"application/json":{}}},"404":{"description":"No documentation entries found for the specified asset","content":{"application/json":{}}}}}},"/v1/documents/{documentIdentifier}/content":{"get":{"tags":["Documents"],"operationId":"showFileContentDefault","parameters":[{"name":"documentIdentifier","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"type":"string","format":"binary"}}}}}}}},"components":{"schemas":{"Asset":{"type":"object","description":"Information concerning the location in which the file will be uploaded (BUILDING_GROUP, BUILDING)","properties":{"uid":{"type":["string","null"],"description":"Optional unique identifier for the asset. Known by the system.","example":"123e4567-e89b-12d3-a456-426614174003"},"externalIds":{"type":"object","additionalProperties":{"type":"string"},"description":"Optional external asset identifiers. Prefer `uid` when known. Otherwise, provide a generic code such as `{ \"code\": \"0018\" }`.","example":{"code":"0018"}}},"required":["externalIds"]},"Documentation":{"type":"object","description":"Information concerning the documentation the file will be uploaded","properties":{"uid":{"type":["string","null"],"description":"Optional unique identifier for the documentation. Known by the system.","example":"123e4567-e89b-12d3-a456-426614174004"},"template":{"type":["string","null"],"description":"Optional unique identifier for the documentation template. Known by the system.","example":"123e4567-e89b-12d3-a456-426614174005"}}},"Folder":{"type":"object","description":"Folder information where the file should be stored","properties":{"uid":{"type":["string","null"],"description":"Optional unique identifier of the target folder","example":"123e4567-e89b-12d3-a456-426614174005"},"template":{"type":["string","null"],"description":"Optional template ID to apply to the folder","example":"123e4567-e89b-12d3-a456-426614174006"}}},"JsonNode":{"type":"object","properties":{"empty":{"type":"boolean"},"array":{"type":"boolean"},"null":{"type":"boolean"},"object":{"type":"boolean"},"float":{"type":"boolean"},"textual":{"type":"boolean","deprecated":true},"integralNumber":{"type":"boolean"},"floatingPointNumber":{"type":"boolean"},"valueNode":{"type":"boolean"},"container":{"type":"boolean"},"missingNode":{"type":"boolean"},"pojo":{"type":"boolean"},"bigDecimal":{"type":"boolean"},"bigInteger":{"type":"boolean"},"boolean":{"type":"boolean"},"double":{"type":"boolean"},"int":{"type":"boolean"},"long":{"type":"boolean"},"short":{"type":"boolean"},"number":{"type":"boolean"},"string":{"type":"boolean"},"binary":{"type":"boolean"},"nodeType":{"type":"string","enum":["ARRAY","BINARY","BOOLEAN","MISSING","NULL","NUMBER","OBJECT","POJO","STRING"]},"embeddedValue":{"type":"boolean"}}},"LinkedAssetReference":{"type":"object","description":"Reference to a linked asset","properties":{"uid":{"type":["string","null"],"description":"Linked asset uid","example":"123e4567-e89b-12d3-a456-426614174999"},"code":{"type":["string","null"],"description":"Linked asset code","example":"RU-001"}}},"ManifestView":{"type":"object","description":"Manifest containing contextual details about the file upload. All fields are optional.","properties":{"asset":{"oneOf":[{"$ref":"#/components/schemas/Asset"},{"type":"null"}]},"documentation":{"oneOf":[{"$ref":"#/components/schemas/Documentation"},{"type":"null"}]},"tags":{"oneOf":[{"$ref":"#/components/schemas/TagsView"},{"type":"null"}]},"properties":{"oneOf":[{"$ref":"#/components/schemas/JsonNode"},{"type":"null"}]},"linkedAssets":{"type":["array","null"],"description":"Linked assets to associate, provided as a list of references by `uid` or `code`.","example":[{"code":"RU-001"},{"uid":"123e4567-e89b-12d3-a456-426614174999"}],"items":{"$ref":"#/components/schemas/LinkedAssetReference"}},"disconnected":{"type":["boolean","null"],"description":"Flag indicating if the file is uploaded without asset context","example":false},"folder":{"oneOf":[{"$ref":"#/components/schemas/Folder"},{"type":"null"}]},"documentClass":{"type":["string","null"],"description":"Existing DocumentClass ID to link","example":"123e4567-e89b-12d3-a456-426614174007"},"temporary":{"type":"boolean","default":false,"description":"Temporary flag allow to delete a file after processing","example":true}},"required":["temporary"]},"TagsView":{"type":"object","description":"Tags applied to the uploaded document","properties":{"documentation":{"type":["array","null"],"description":"Documentation tags linked to the documentation","example":"['EDP 2024']","items":{"type":"string"},"uniqueItems":true}}},"UploadRequest":{"type":"object","description":"Multipart form-data with a file and a JSON manifest","properties":{"file":{"type":["string","null"],"format":"binary","description":"The main file to upload (PDF, image, etc.)"},"manifest":{"type":["string","null"],"format":"binary","description":"Manifest as a JSON file"}},"required":["file","manifest"]},"FileUploadedResponse":{"type":"object","description":"Response returned after successfully uploading a file","properties":{"documentId":{"type":"string","description":"Unique identifier of the uploaded document","example":"123e4567-e89b-12d3-a456-426614174000"},"duplicateDocumentIds":{"type":"array","description":"List of IDs for any duplicate documents that were detected during upload","example":["123e4567-e89b-12d3-a456-426614174001","123e4567-e89b-12d3-a456-426614174002"],"items":{"type":"string"}}},"required":["documentId","duplicateDocumentIds"]},"DocumentSearchFilter":{"type":"object","description":"Document search filters","properties":{"identifiers":{"type":["array","null"],"items":{"type":"string"},"uniqueItems":true},"assetIdentifiers":{"type":["array","null"],"items":{"type":"string"},"uniqueItems":true},"documentationIdentifiers":{"type":["array","null"],"items":{"type":"string"},"uniqueItems":true},"folderIdentifiers":{"type":["array","null"],"items":{"type":"string"},"uniqueItems":true},"tags":{"type":["array","null"],"items":{"type":"string"},"uniqueItems":true},"properties":{"type":["object","null"],"additionalProperties":{"type":"string"}},"propertyPath":{"type":["object","null"],"additionalProperties":{"type":"object","additionalProperties":{"type":"string"}}},"propertyKey":{"type":["string","null"]},"name":{"type":["string","null"]},"uploadedBy":{"type":["string","null"]},"documentStatus":{"type":["string","null"]},"parentFolderName":{"type":["string","null"]},"predictedFolderName":{"type":["string","null"]},"folder":{"oneOf":[{"$ref":"#/components/schemas/SearchedFolder"},{"type":"null"}]},"documentClass":{"oneOf":[{"$ref":"#/components/schemas/SearchedDocumentClass"},{"type":"null"}]},"tenantIdentifiers":{"type":["array","null"],"items":{"type":"string"},"uniqueItems":true},"linkedAssetIdentifiers":{"type":["array","null"],"items":{"type":"string"},"uniqueItems":true},"linkedAsset":{"type":["string","null"]},"hashSha256":{"type":["string","null"]},"hasMetadata":{"type":["boolean","null"]},"hasLinkedAssets":{"type":["boolean","null"]},"hasPendingSuggestion":{"type":["boolean","null"],"description":"Filter documents with an AI classification suggestion pending human validation (an AI-predicted folder and document class exist but have not been manually validated yet)","example":true}}},"SearchedDocumentClass":{"type":"object","properties":{"code":{"type":["string","null"],"description":"Document class code filter","example":"DIAGNOSTIC_ELECTRICITE"},"name":{"type":["string","null"],"description":"Localized document class name filter","example":"Diagnostic electricite"},"locale":{"type":["string","null"],"description":"Locale used with the document class name filter","example":"fr-FR"}}},"SearchedFolder":{"type":"object","properties":{"name":{"type":"string"},"locale":{"type":"string"}},"required":["locale","name"]},"ClassificationReferenceDocumentView":{"type":"object","description":"Information about a document used for classification","properties":{"fileResourceUid":{"type":"string","description":"Unique identifier of the file resource","example":"4ga1328c-f97b-59f3-91c6-cg623beg4233"},"documentUid":{"type":"string","description":"Unique identifier of the document","example":"3fa1968c-f86a-48e2-80b5-bf512adf3122"},"cosineSimilarity":{"type":"string","description":"Similarity score between this document and the classified document","example":"0.99997663"},"name":{"type":"string","description":"Name of the document used for classification","example":"dpe.pdf"}},"required":["cosineSimilarity","documentUid","fileResourceUid","name"]},"DocumentFolderView":{"type":"object","description":"Information about a document folder","properties":{"identifier":{"type":"string","description":"Unique identifier of the folder","example":"folder-123e4567-e89b-12d3-a456-426614174000"},"names":{"type":"array","description":"Localized names of the folder in different languages","items":{"$ref":"#/components/schemas/LocalisedNameView"},"uniqueItems":true}},"required":["identifier","names"]},"DocumentLocationView":{"type":"object","description":"Location information of a document within a documentation structure","properties":{"documentationIdentifier":{"type":["string","null"],"description":"Identifier of the documentation","example":"doc-123e4567-e89b-12d3-a456-426614174000"},"path":{"type":"array","description":"Path to the document in the folder structure","items":{"$ref":"#/components/schemas/DocumentPathView"}}},"required":["path"]},"DocumentPathView":{"type":"object","description":"Information about a node in the document path","properties":{"identifier":{"type":["string","null"],"description":"Identifier of the path node","example":"folder-123e4567-e89b-12d3-a456-426614174000"},"names":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Localized names of the path node mapped by language code","example":{"en":"Invoices","fr":"Factures"}}}},"DocumentReferenceView":{"type":"object","description":"Reference to an entity related to the document","properties":{"referencedEntityType":{"type":["string","null"],"description":"Type of the referenced entity","example":"ASSET"},"entityIdentifier":{"type":["string","null"],"description":"Identifier of the referenced entity","example":"asset-123e4567-e89b-12d3-a456-426614174000"},"documentationIdentifier":{"type":["string","null"],"description":"Identifier of the documentation","example":"doc-123e4567-e89b-12d3-a456-426614174000"},"folder":{"oneOf":[{"$ref":"#/components/schemas/DocumentFolderView"},{"type":"null"}]},"documentLocationView":{"oneOf":[{"$ref":"#/components/schemas/DocumentLocationView"},{"type":"null"}]},"templateFolder":{"oneOf":[{"$ref":"#/components/schemas/DocumentTemplateFolderView"},{"type":"null"}]},"manuallyValidated":{"type":"boolean","description":"Whether this specific reference was manually validated by a user","example":false}},"required":["manuallyValidated"]},"DocumentTemplateFolderView":{"type":"object","description":"Information about a document template folder","properties":{"identifier":{"type":"string","description":"Unique identifier of the template folder","example":"template-folder-123e4567-e89b-12d3-a456-426614174000"},"names":{"type":["array","null"],"description":"Localized names of the template folder in different languages","items":{"$ref":"#/components/schemas/LocalisedNameView"},"uniqueItems":true}},"required":["identifier"]},"DocumentView":{"type":"object","description":"Comprehensive view of a document with all its metadata and references","properties":{"identifier":{"type":"string","description":"Unique identifier of the document","example":"doc-123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Name of the document","example":"Invoice-2023.pdf"},"fileResource":{"$ref":"#/components/schemas/FileResourceView","description":"File resource information including identifier, name, import date and content type"},"documentClass":{"oneOf":[{"$ref":"#/components/schemas/EmbeddedDocumentClassView"},{"type":"null"}]},"predictedDocumentClass":{"oneOf":[{"$ref":"#/components/schemas/PredictedDocumentClassView"},{"type":"null"}]},"predictedFolder":{"oneOf":[{"$ref":"#/components/schemas/PredictedFolderView"},{"type":"null"}]},"classificationStatus":{"type":["string","null"],"description":"Current classification status of the document","example":"MANUAL"},"manuallyValidatedFolder":{"oneOf":[{"$ref":"#/components/schemas/DocumentFolderView"},{"type":"null"}]},"documentationTags":{"type":"array","description":"Tags associated with the document in its documentation","items":{"$ref":"#/components/schemas/TagView"},"uniqueItems":true},"properties":{"type":["object","null"],"additionalProperties":{},"description":"Custom properties associated with the document"},"suggestedMetadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Metadata suggested by AI or other automated processes"},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Validated metadata associated with the document"},"documentReferences":{"type":"array","description":"References to other entities like assets or folders","items":{"$ref":"#/components/schemas/DocumentReferenceView"},"uniqueItems":true},"urlAccess":{"type":["string","null"],"description":"URL to access the document content","example":"https://example.com/api/documents/doc-123/content"},"creationDate":{"type":["string","null"],"format":"date-time","description":"Date and time when the document was created","example":"2023-01-15T14:30:00"},"updateDate":{"type":["string","null"],"format":"date-time","description":"Date and time when the document was last updated","example":"2023-02-20T09:45:00"},"hash":{"type":["string","null"],"description":"Hash value of the document content for integrity verification","example":"a1b2c3d4e5f6..."},"linkedAssets":{"type":"array","description":"Linked assets associated with this document","items":{"$ref":"#/components/schemas/LinkedAssetView"},"uniqueItems":true},"tenants":{"type":"array","description":"Tenants associated with this document","items":{"$ref":"#/components/schemas/TenantView"},"uniqueItems":true},"docsUsedToClassify":{"type":"array","description":"Documents used for classification","items":{"$ref":"#/components/schemas/ClassificationReferenceDocumentView"},"uniqueItems":true},"uploadedBy":{"type":["string","null"],"description":"Identifier of the user who uploaded the document"},"isDuplicated":{"type":["boolean","null"]},"isFiled":{"type":"boolean"},"isFiledByAI":{"type":"boolean"}},"required":["docsUsedToClassify","documentReferences","documentationTags","fileResource","identifier","isFiledByAI","linkedAssets","name","tenants"]},"EmbeddedDocumentClassView":{"type":"object","description":"Information about the validated document class","properties":{"documentClassCode":{"type":"string","description":"Code of the document class","example":"INVOICE"},"documentClassNames":{"type":"array","description":"Localized names of the document class in different languages","items":{"$ref":"#/components/schemas/LocalisedNameView"},"uniqueItems":true},"documentClassIdentifier":{"type":"string","description":"Unique identifier of the document class","example":"class-123e4567-e89b-12d3-a456-426614174000"},"metadataTypes":{"type":"array","description":"Metadata types associated with the document class","items":{"$ref":"#/components/schemas/MetadataTypeView"},"uniqueItems":true}},"required":["documentClassCode","documentClassIdentifier","documentClassNames","metadataTypes"]},"FileResourceView":{"type":"object","description":"Information about the file resource associated with a document","properties":{"identifier":{"type":"string","description":"Unique identifier of the file resource","example":"file-123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Name of the file","example":"Invoice-2023.pdf"},"importDate":{"type":"string","description":"Date when the file was imported","example":"2023-01-15T14:30:00"},"contentType":{"type":["string","null"],"description":"Content type (MIME type) of the file","example":"application/pdf"}},"required":["identifier","importDate","name"]},"LinkedAssetView":{"type":"object","description":"Information about a linked asset","properties":{"uid":{"type":"string","description":"Unique identifier of the linked asset","example":"asset-123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","description":"Display name of the linked asset","example":"RU-001 - Apartment 42B"}},"required":["name","uid"]},"LocalisedNameView":{"type":"object","description":"Localized name information with language code","properties":{"name":{"type":"string","description":"The name in the specified language","example":"Root folder"},"locale":{"type":"string","description":"Language code (ISO 639-1)","example":"en-US"}},"required":["locale","name"]},"MetadataTypeView":{"type":"object","properties":{"identifier":{"type":"string"},"code":{"type":"string"},"names":{"type":"array","items":{"$ref":"#/components/schemas/LocalisedNameView"},"uniqueItems":true},"format":{"type":"string"},"unit":{"type":["string","null"]},"description":{"type":["string","null"]}},"required":["code","format","identifier","names"]},"PageResultOfDocumentView":{"type":"object","description":"Paged list of documents","properties":{"result":{"type":"array","description":"List of documents in this page","items":{"$ref":"#/components/schemas/DocumentView"}},"total":{"type":"integer","format":"int64","description":"Total number of matching documents","example":123},"pageable":{"$ref":"#/components/schemas/Pageable","description":"Pagination details (pageNumber starts at 1)"}},"required":["pageable","result","total"]},"Pageable":{"type":"object","properties":{"pageNumber":{"type":["integer","null"],"format":"int64","description":"Page number (starts at 1 in API responses; 0 is accepted in requests for backward compatibility)","example":1},"pageSize":{"type":["integer","null"],"format":"int64","description":"Page size","example":25},"sort":{"$ref":"#/components/schemas/Sort"},"afterId":{"type":["integer","null"],"format":"int64"},"afterValue":{"type":["string","null"],"format":"date-time"},"cursorSortColumn":{"type":["string","null"]},"updateDateCursor":{"type":"boolean"}},"required":["sort"]},"PredictedDocumentClassView":{"type":"object","description":"Information about the document class predicted by AI","properties":{"predictedDocumentClassCode":{"type":"string","description":"Code of the predicted document class","example":"INVOICE"},"confidenceIndex":{"type":["number","null"],"format":"double","description":"Confidence level of the prediction (0-1)","example":0.85},"predictedDocumentClassIdentifier":{"type":"string","description":"Unique identifier of the predicted document class","example":"class-123e4567-e89b-12d3-a456-426614174000"},"predictedDocumentClassNames":{"type":"array","description":"Localized names of the predicted document class in different languages","items":{"$ref":"#/components/schemas/LocalisedNameView"},"uniqueItems":true}},"required":["predictedDocumentClassCode","predictedDocumentClassIdentifier","predictedDocumentClassNames"]},"PredictedFolderView":{"type":"object","description":"Information about the folder predicted by AI","properties":{"identifier":{"type":"string","description":"Unique identifier of the predicted folder","example":"folder-123e4567-e89b-12d3-a456-426614174000"},"names":{"type":"array","description":"Localized names of the predicted folder in different languages","items":{"$ref":"#/components/schemas/LocalisedNameView"},"uniqueItems":true}},"required":["identifier","names"]},"Sort":{"type":"object","properties":{"fieldOrder":{"type":"object","additionalProperties":{"type":"string","enum":["ASC","DESC"]}}},"required":["fieldOrder"]},"TagView":{"type":"object","description":"Represents a tag assigned to a documentation.","properties":{"id":{"type":"integer","format":"int32","description":"Tag ID","example":1},"documentationIdentifier":{"type":"string","description":"Documentation identifier associated with the tag","example":"doc-789"},"name":{"type":"string","description":"Name of the tag","example":"Important"},"color":{"type":["string","null"],"description":"Optional color for the tag (HEX code)","example":"#FF5733"}},"required":["documentationIdentifier","id","name"]},"TenantView":{"type":"object","description":"Represents a tenant linked to a document.","properties":{"uid":{"type":"string","description":"Unique identifier of the tenant","example":"tenant-123"},"name":{"type":"string","description":"Name of the tenant","example":"John Doe"}},"required":["name","uid"]},"UpdateDocumentDocumentationTagsItemRequest":{"type":"object","description":"Tag update instruction scoped to a document and a documentation","properties":{"assetIdentifier":{"type":"string","description":"Asset identifier that scopes access validation for this item","example":"asset-789"},"documentIdentifier":{"type":"string","description":"Document identifier","example":"doc-123"},"documentationIdentifier":{"type":"string","description":"Documentation identifier to which the tags belong","example":"documentation-456"},"addTags":{"type":"array","description":"Documentation tags to add to the document. Missing tags are created before assignment","items":{"type":"string"}},"removeTags":{"type":"array","description":"Documentation tags to remove from the document for the targeted documentation only","items":{"type":"string"}}},"required":["addTags","assetIdentifier","documentIdentifier","documentationIdentifier","removeTags"]},"UpdateDocumentDocumentationTagsRequest":{"type":"object","description":"Request to add or remove documentation tags on documents across multiple documentations","properties":{"items":{"type":"array","description":"Items to process in the same transaction, each scoped to a document and a documentation","items":{"$ref":"#/components/schemas/UpdateDocumentDocumentationTagsItemRequest"}}},"required":["items"]},"TemplateListItem":{"type":"object","description":"Documentation template entry exposed in the public API","properties":{"id":{"type":"string","description":"Template unique identifier","example":"f90ee77d-b6cc-41fa-8d1f-bea649e6d93d"},"name":{"type":"string","description":"Template name in the requested language","example":{"fr-FR":"DOE"}},"organizationCode":{"type":"string","description":"Organization code","example":"13_HABITAT"},"attachmentType":{"type":"string","description":"Attachment type","example":"BUILDING_GROUP"}},"required":["attachmentType","id","name","organizationCode"]},"TemplatesListResponse":{"type":"object","description":"Response containing documentation templates for an organization","properties":{"templates":{"type":"array","items":{"$ref":"#/components/schemas/TemplateListItem"}}},"required":["templates"]},"TemplateFolderDetail":{"type":"object","description":"Folder within a documentation template","properties":{"id":{"type":"string","description":"Folder unique identifier"},"name":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized names keyed by locale limited to the requested language"},"parentId":{"type":["string","null"],"description":"Parent folder identifier. Null for root folders."},"documentClass":{"oneOf":[{"$ref":"#/components/schemas/TemplateFolderDocumentClass"},{"type":"null"}]}},"required":["id","name"]},"TemplateFolderDocumentClass":{"type":"object","description":"Document class linked to a documentation template folder","properties":{"identifier":{"type":"string","description":"Document class identifier","example":"documentClassIdentifier"},"code":{"type":"string","description":"Document class code","example":"DPE"}},"required":["code","identifier"]},"TemplateDetail":{"type":"object","description":"Documentation template description with its metadata and folders","properties":{"id":{"type":"string","description":"Template unique identifier"},"name":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized names keyed by locale limited to the requested language"},"organizationCode":{"type":"string","description":"Organization code"},"attachmentType":{"type":"string","description":"Attachment type"},"folders":{"type":"array","items":{"$ref":"#/components/schemas/TemplateFolderDetail"}}},"required":["attachmentType","folders","id","name","organizationCode"]},"TemplateDetailResponse":{"type":"object","description":"Response containing a documentation template with its folder tree","properties":{"template":{"$ref":"#/components/schemas/TemplateDetail","description":"Documentation template"}},"required":["template"]},"AssetResponse":{"type":"object","description":"`name`/`type`/`externalIdentifier` are null when the referenced asset can't be resolved; `identifier` is always present","properties":{"identifier":{"type":"string"},"name":{"type":["string","null"]},"type":{"type":["string","null"]},"externalIdentifier":{"type":["string","null"],"description":"The asset's identifier in an external system (e.g. an ERP), when known"}},"required":["identifier"]},"ClassificationReferenceDocumentResponse":{"type":"object","properties":{"fileResourceUid":{"type":"string"},"documentUid":{"type":"string"},"cosineSimilarity":{"type":"string"},"name":{"type":"string"}},"required":["cosineSimilarity","documentUid","fileResourceUid","name"]},"ContentTypeResponse":{"type":"object","properties":{"mediaType":{"type":"string","example":"application/pdf"},"charset":{"type":["string","null"]}},"required":["mediaType"]},"DocumentClassResponse":{"type":"object","properties":{"identifier":{"type":"string"},"code":{"type":"string"},"names":{"type":"object","additionalProperties":{"type":"string"}}},"required":["code","identifier","names"]},"DocumentClassificationResponse":{"type":"object","description":"Classification information — present when requested via include=classification or include=all","properties":{"classificationStatus":{"type":["string","null"]},"documentClass":{"oneOf":[{"$ref":"#/components/schemas/DocumentClassResponse"},{"type":"null"}]},"predictedDocumentClass":{"oneOf":[{"$ref":"#/components/schemas/PredictedDocumentClassResponse"},{"type":"null"}]},"predictedFolder":{"oneOf":[{"$ref":"#/components/schemas/PredictedFolderResponse"},{"type":"null"}]},"docsUsedToClassify":{"type":"array","items":{"$ref":"#/components/schemas/ClassificationReferenceDocumentResponse"}}},"required":["docsUsedToClassify"]},"DocumentDetailResponse":{"type":"object","description":"A single document's detail response. `identity` and `file` are always present; every other section is present only when requested via the `include` query parameter.","properties":{"identity":{"$ref":"#/components/schemas/DocumentIdentityResponse"},"file":{"$ref":"#/components/schemas/DocumentFileResponse"},"classification":{"oneOf":[{"$ref":"#/components/schemas/DocumentClassificationResponse"},{"type":"null"}]},"tags":{"oneOf":[{"$ref":"#/components/schemas/DocumentTagsResponse"},{"type":"null"}]},"metadata":{"type":["array","null"],"items":{"$ref":"#/components/schemas/DocumentMetadataEntryResponse"}},"linkedAssets":{"oneOf":[{"$ref":"#/components/schemas/LinkedAssetsResponse"},{"type":"null"}]},"stakeholders":{"oneOf":[{"$ref":"#/components/schemas/StakeholdersResponse"},{"type":"null"}]},"lifecycle":{"oneOf":[{"$ref":"#/components/schemas/DocumentLifecycleResponse"},{"type":"null"}]},"references":{"type":["array","null"],"items":{"$ref":"#/components/schemas/DocumentReferenceResponse"}}},"required":["file","identity"]},"DocumentFileResponse":{"type":"object","description":"File information — always present. `size`/`contentType` may be absent if that information can't be resolved.","properties":{"size":{"type":["integer","null"],"format":"int64","example":1088229},"contentType":{"oneOf":[{"$ref":"#/components/schemas/ContentTypeResponse"},{"type":"null"}]}}},"DocumentIdentityResponse":{"type":"object","description":"Core document identity — always present","properties":{"identifier":{"type":"string","example":"43065ec3-04d7-4613-b22a-a9b851eb1616"},"organizationCode":{"type":["string","null"],"example":"DEMO"},"name":{"type":"string","example":"DPE_2017 (1).pdf"},"fileIdentifier":{"type":"string","example":"fa692f4d-93e7-415a-86d3-12f2f1d7131e"}},"required":["fileIdentifier","identifier","name"]},"DocumentLifecycleResponse":{"type":"object","description":"Lifecycle timestamps — present when requested via include=lifecycle or include=all","properties":{"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"uploadedBy":{"type":["string","null"]},"deletedAt":{"type":["string","null"],"format":"date-time"},"deletedBy":{"type":["string","null"]}},"required":["createdAt","updatedAt"]},"DocumentMetadataEntryResponse":{"type":"object","description":"One entry per metadata field defined by the document's class — present when requested via include=metadata or include=all","properties":{"code":{"type":"string"},"value":{"type":["string","null"]},"suggestedValue":{"type":["string","null"],"description":"Raw AI-suggested value for this field, independent of value's own resolution — compare against value to tell whether it is still AI-extracted or has been human-validated/edited"},"metadataType":{"oneOf":[{"$ref":"#/components/schemas/MetadataTypeResponse"},{"type":"null"}]}},"required":["code"]},"DocumentReferenceResponse":{"type":"object","description":"Where the document is filed (asset/documentation/folder) — present when requested via include=references or include=all","properties":{"asset":{"oneOf":[{"$ref":"#/components/schemas/AssetResponse"},{"type":"null"}]},"documentation":{"oneOf":[{"$ref":"#/components/schemas/DocumentationReferenceResponse"},{"type":"null"}]},"folder":{"oneOf":[{"$ref":"#/components/schemas/ReferenceFolderResponse"},{"type":"null"}]}}},"DocumentTagsResponse":{"type":"object","description":"Tags — present when requested via include=tags or include=all","properties":{"documentationTags":{"type":"array","items":{"$ref":"#/components/schemas/DocumentationTagResponse"}},"tags":{"type":"array","items":{"type":"string"}}},"required":["documentationTags","tags"]},"DocumentationReferenceResponse":{"type":"object","properties":{"identifier":{"type":"string"},"names":{"type":"object","additionalProperties":{"type":"string"}}},"required":["identifier","names"]},"DocumentationTagResponse":{"type":"object","properties":{"identifier":{"type":"integer","format":"int32"},"documentationIdentifier":{"type":"string"},"name":{"type":"string"},"color":{"type":["string","null"]}},"required":["documentationIdentifier","identifier","name"]},"LinkedAssetsResponse":{"type":"object","description":"Assets linked to the document (uid → name) — present when requested via include=linkedAssets or include=all","properties":{"names":{"type":"object","additionalProperties":{"type":"string"}}},"required":["names"]},"MetadataTypeResponse":{"type":"object","properties":{"identifier":{"type":"string"},"names":{"type":"object","additionalProperties":{"type":"string"}},"format":{"type":"string"},"unit":{"type":["string","null"]},"description":{"type":["string","null"]}},"required":["format","identifier","names"]},"PredictedDocumentClassResponse":{"type":"object","properties":{"predictedDocumentClassIdentifier":{"type":"string"},"predictedDocumentClassCode":{"type":"string"},"predictedDocumentClassNames":{"type":"object","additionalProperties":{"type":"string"}},"confidenceIndex":{"type":["number","null"],"format":"double"}},"required":["predictedDocumentClassCode","predictedDocumentClassIdentifier","predictedDocumentClassNames"]},"PredictedFolderResponse":{"type":"object","properties":{"identifier":{"type":"string"},"names":{"type":"object","additionalProperties":{"type":"string"}}},"required":["identifier","names"]},"ReferenceFolderResponse":{"type":"object","properties":{"identifier":{"type":"string"},"names":{"type":"object","additionalProperties":{"type":"string"}},"manuallyValidated":{"type":"boolean"}},"required":["identifier","manuallyValidated","names"]},"StakeholdersResponse":{"type":"object","description":"Stakeholders on the document (uid → name) — present when requested via include=stakeholders or include=all","properties":{"names":{"type":"object","additionalProperties":{"type":"string"}}},"required":["names"]},"DocumentationResponseView":{"type":"object","description":"Detailed information about a documentation entry","properties":{"identifier":{"type":"string","description":"Unique identifier of the documentation","example":"123e4567-e89b-12d3-a456-426614174000"},"organizationCode":{"type":"string","description":"Organization code that owns this documentation","example":"ORG123"},"assetIdentifier":{"type":"string","description":"Identifier of the asset this documentation belongs to","example":"3e6e000-919b-8762-108d-deb9f1595dr"},"documentationTemplateReference":{"type":["string","null"],"description":"Reference to the documentation template if applicable","example":"2d6e099-910b-4668-902c-deb9f15984ec"},"documentationTemplateAttachmentType":{"type":["string","null"],"description":"Type of attachment for the documentation template","example":"ASSET"},"names":{"type":"array","description":"Set of localized names for this documentation","example":[{"name":"Documentation 1","locale":"en-US"}],"items":{"$ref":"#/components/schemas/LocalisedNameView"},"uniqueItems":true},"rootFolder":{"$ref":"#/components/schemas/FolderResponseView","deprecated":true,"description":"Root folder (backward-compatible alias of rootTemplate — will be removed in a future release)"},"rootTemplate":{"$ref":"#/components/schemas/TemplateFolderResponseView","description":"Root template folder (canonical durable projection sourced from documentationtemplatefolders)"}},"required":["assetIdentifier","identifier","names","organizationCode","rootFolder","rootTemplate"]},"DocumentationSimplifiedView":{"type":"object","description":"Response containing a set of documentation entries for an asset","properties":{"result":{"type":"array","description":"Collection of documentation entries","items":{"$ref":"#/components/schemas/DocumentationResponseView"},"uniqueItems":true}},"required":["result"]},"FolderResponseView":{"type":"object","description":"Folder structure (backward-compatible alias of TemplateFolderResponseView)","properties":{"identifier":{"type":"string"},"documentationTemplateFolderReference":{"type":["string","null"]},"names":{"type":"array","items":{"$ref":"#/components/schemas/LocalisedNameView"},"uniqueItems":true},"folders":{"type":"array","items":{"$ref":"#/components/schemas/FolderResponseView"}}},"required":["folders","identifier","names"]},"TemplateFolderResponseView":{"type":"object","description":"Root template folder projection for a documentation entry (canonical durable shape sourced from documentationtemplatefolders)","properties":{"identifier":{"type":"string"},"names":{"type":"array","items":{"$ref":"#/components/schemas/LocalisedNameView"},"uniqueItems":true},"folders":{"type":"array","items":{"$ref":"#/components/schemas/TemplateFolderResponseView"}}},"required":["folders","identifier","names"]}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}