{"openapi":"3.0.0","paths":{"/v1/health":{"get":{"description":"Liveness of the public API.","operationId":"V1PublicController_health","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"summary":"Health","tags":["Meta"],"x-brault-plane":"both"}},"/v1/me":{"get":{"description":"The brandspace, key, creator, plan and limits behind the presented API key — and, because this route is central, where the brandspace lives and which host to dial for its content. There is no separate region endpoint.","operationId":"MetaController_me","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyContextDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Who am I","tags":["Meta"],"x-brault-plane":"central","servers":[{"url":"https://api.brault.app"}]}},"/v1/usage":{"get":{"description":"Counters for the current windows and the monthly quota of the brandspace.","operationId":"MetaController_usage","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Current usage","tags":["Meta"],"x-brault-plane":"central","servers":[{"url":"https://api.brault.app"}]}},"/v1/events":{"get":{"description":"Every event type a webhook endpoint can subscribe to, with its group, a one-line description and the `object` its payload’s `data` carries. Put these tokens in a webhook’s `events`, or the single element \"*\" to receive everything, including event types added later.","operationId":"MetaController_events","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventTypeListDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"The webhook event catalogue","tags":["Meta"],"x-brault-plane":"central","servers":[{"url":"https://api.brault.app"}]}},"/v1/libraries":{"get":{"description":"Libraries the key’s creator can see.","operationId":"V1LibrariesController_list","parameters":[{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from a previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LibraryListDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"List libraries","tags":["Libraries"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"post":{"operationId":"V1LibrariesController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLibraryBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LibraryDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Create a library","tags":["Libraries"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/libraries/{libraryId}":{"get":{"operationId":"V1LibrariesController_retrieve","parameters":[{"name":"libraryId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LibraryDetailDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Retrieve a library","tags":["Libraries"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"patch":{"description":"Only `name` and `description` are settable.","operationId":"V1LibrariesController_update","parameters":[{"name":"libraryId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateLibraryBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LibraryDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Update a library","tags":["Libraries"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"delete":{"operationId":"V1LibrariesController_remove","parameters":[{"name":"libraryId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Delete a library","tags":["Libraries"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/folders":{"get":{"description":"The folder tree the key’s creator can see. Paginated in the API layer.","operationId":"V1FoldersController_list","parameters":[{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from a previous response.","schema":{"type":"string"}},{"name":"library_id","required":false,"in":"query","description":"Restrict to one library.","schema":{"type":"string"}},{"name":"folder_id","required":false,"in":"query","description":"Restrict to the children of one folder.","schema":{"type":"string"}},{"name":"recursive","required":false,"in":"query","description":"Include every descendant, not only direct children.","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderListDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"List folders","tags":["Folders"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"post":{"operationId":"V1FoldersController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFolderBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Create a folder","tags":["Folders"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/folders/{folderId}":{"get":{"operationId":"V1FoldersController_retrieve","parameters":[{"name":"folderId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderDetailDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Retrieve a folder","tags":["Folders"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"patch":{"operationId":"V1FoldersController_update","parameters":[{"name":"folderId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFolderBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Rename or recolor a folder","tags":["Folders"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"delete":{"description":"Moves the folder to the trash. `permanent=true` deletes it and its contents irreversibly.","operationId":"V1FoldersController_remove","parameters":[{"name":"folderId","required":true,"in":"path","schema":{"type":"string"}},{"name":"permanent","required":false,"in":"query","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Trash or permanently delete a folder","tags":["Folders"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/folders/{folderId}/move":{"post":{"description":"Give exactly one of `library_id`, `folder_id`. A folder always belongs to a library, so there is no move to the brandspace root.","operationId":"V1FoldersController_move","parameters":[{"name":"folderId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveFolderBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Move a folder","tags":["Folders"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/folders/{folderId}/restore":{"post":{"operationId":"V1FoldersController_restore","parameters":[{"name":"folderId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Restore a trashed folder","tags":["Folders"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/files/import":{"post":{"description":"Downloads a public http(s) URL into the brandspace. Asynchronous: poll /v1/imports/{import_id}. Maximum 5 GiB, 2 concurrent imports per brandspace.","operationId":"V1ImportsController_start","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartImportBodyDto"}}}},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Import a file from a URL","tags":["Imports"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/imports/{importId}":{"get":{"operationId":"V1ImportsController_retrieve","parameters":[{"name":"importId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Retrieve an import","tags":["Imports"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/files":{"get":{"description":"Files the key’s creator can see. Folders are never included. `q` runs the same keyword + natural-language search as the app and consumes the search rate bucket.","operationId":"V1FilesListController_list","parameters":[{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from a previous response.","schema":{"type":"string"}},{"name":"library_id","required":false,"in":"query","schema":{"type":"string"}},{"name":"folder_id","required":false,"in":"query","schema":{"type":"string"}},{"name":"recursive","required":false,"in":"query","description":"Include files in every descendant folder.","schema":{"default":false,"type":"boolean"}},{"name":"q","required":false,"in":"query","description":"Keyword and natural-language search. Consumes the search rate bucket.","schema":{"maxLength":500,"type":"string"}},{"name":"extensions","required":false,"in":"query","description":"Comma-separated extensions, without the dot.","schema":{"type":"array","items":{"type":"string"}}},{"name":"kind","required":false,"in":"query","schema":{"type":"array","items":{"type":"string","enum":["image","video","audio","document","link","other"]}}},{"name":"created_after","required":false,"in":"query","schema":{"format":"date-time","type":"string"}},{"name":"created_before","required":false,"in":"query","schema":{"format":"date-time","type":"string"}},{"name":"uploaded_by","required":false,"in":"query","description":"Comma-separated user ids.","schema":{"type":"array","items":{"type":"string"}}},{"name":"min_size","required":false,"in":"query","description":"Bytes.","schema":{"type":"number"}},{"name":"max_size","required":false,"in":"query","description":"Bytes.","schema":{"type":"number"}},{"name":"filter","required":false,"in":"query","description":"A URL-encoded JSON filter document (boards.md § 5). A condition may name a brandspace property or a board property; a board-property condition matches files through their membership on that property’s board. Combines with every other parameter with AND — which is why a top-level `or` filter cannot be sent together with uploaded_by, extensions, kind, min_size, max_size, created_after or created_before (400 validation_error).","schema":{"maxLength":4096,"type":"string"}},{"name":"sort","required":false,"in":"query","schema":{"default":"created_at","type":"string","enum":["name","size","created_at"]}},{"name":"order","required":false,"in":"query","schema":{"default":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileListDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"List files","tags":["Files"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/files/{fileId}":{"get":{"description":"Full metadata plus renditions signed for 15 minutes. The original file is NOT included here — request it from /v1/files/{fileId}/download, which counts against the download limit.","operationId":"V1FilesController_retrieve","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileDetailDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Retrieve a file","tags":["Files"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"patch":{"description":"Rename, replace the tag set, or point a link file at a new URL. Every field is optional.","operationId":"V1FilesController_update","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFileBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileDetailDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Update a file","tags":["Files"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"delete":{"description":"Moves the file to the trash. `permanent=true` deletes the file and its versions irreversibly.","operationId":"V1FilesController_remove","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}},{"name":"permanent","required":false,"in":"query","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Trash or permanently delete a file","tags":["Files"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/files/{fileId}/download":{"get":{"description":"A signed URL for the file, valid 15 minutes. Counts against the plan’s daily download issuances.","operationId":"V1FilesController_download","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}},{"name":"rendition","required":false,"in":"query","schema":{"type":"string","enum":["original","preview","thumbnail"],"default":"original"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileDownloadDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Get a download URL","tags":["Files"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/files/{fileId}/similar":{"get":{"description":"Nearest neighbours of this file’s embedding. Consumes the search rate bucket.","operationId":"V1FilesController_similar","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from a previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimilarFilesDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Find visually similar files","tags":["Files"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/files/{fileId}/move":{"post":{"description":"Give exactly one of `library_id`, `folder_id`, `to_root`.","operationId":"V1FilesController_move","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileDetailDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Move a file","tags":["Files"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/files/{fileId}/copy":{"post":{"description":"Give exactly one of `library_id`, `folder_id`, `to_root`.","operationId":"V1FilesController_copy","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileDetailDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Copy a file","tags":["Files"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/files/{fileId}/properties/{propertyId}":{"put":{"description":"Send exactly one field, named after the property’s type. `null` clears a scalar; tag takes { add, remove }.","operationId":"V1FilesController_setProperty","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}},{"name":"propertyId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetBrandspaceValueBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileDetailDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Set or clear a brandspace property value on a file","tags":["Files"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/files/{fileId}/boards":{"get":{"description":"Only the boards the key’s creator can see. A single page — a file sits on a handful of boards.","operationId":"V1FilesController_boards","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileBoardsListDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"List the boards a file is on","tags":["Files"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/files/{fileId}/restore":{"post":{"operationId":"V1FilesController_restore","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileDetailDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Restore a trashed file","tags":["Files"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/downloads":{"post":{"description":"Asynchronous. Poll /v1/downloads/{download_id} until `status` is `ready`, then use `url`.","operationId":"V1DownloadsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDownloadBodyDto"}}}},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Start a ZIP download","tags":["Downloads"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/downloads/{downloadId}":{"get":{"operationId":"V1DownloadsController_retrieve","parameters":[{"name":"downloadId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Retrieve a ZIP download","tags":["Downloads"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/uploads":{"post":{"description":"Returns a presigned URL (or a multipart session above 256 MiB). PUT the bytes to S3 yourself, then call complete. Send `file_id` to add a version to an existing file.","operationId":"V1UploadsController_start","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartUploadBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Start an upload","tags":["Uploads"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/uploads/{uploadId}/parts":{"post":{"operationId":"V1UploadsController_parts","parameters":[{"name":"uploadId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadPartsBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadPartsDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Get presigned URLs for multipart parts","tags":["Uploads"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/uploads/{uploadId}/complete":{"post":{"description":"Creates the file (or the version) and starts processing. The file’s `status` is `processing`.","operationId":"V1UploadsController_complete","parameters":[{"name":"uploadId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteUploadBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileDetailDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Finish an upload","tags":["Uploads"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/uploads/{uploadId}/abort":{"post":{"operationId":"V1UploadsController_abort","parameters":[{"name":"uploadId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AbortedDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Abort an upload","tags":["Uploads"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/files/{fileId}/versions":{"get":{"description":"Newest first.","operationId":"V1VersionsController_list","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from a previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionListDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"List a file’s versions","tags":["Versions"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/files/{fileId}/versions/{versionId}/activate":{"post":{"operationId":"V1VersionsController_activate","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}},{"name":"versionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Make a version the active one","tags":["Versions"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/files/{fileId}/versions/{versionId}":{"delete":{"description":"Irreversible: the version’s bytes and every comment attached to it are deleted. This is not a trash operation.","operationId":"V1VersionsController_remove","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}},{"name":"versionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Delete a version","tags":["Versions"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/files/{fileId}/comments":{"get":{"description":"Oldest first. Filter with resolved and version_id. format=csv answers text/csv with every matching comment and its replies, ignoring limit and cursor. A page (file_type canvas) is a valid file here; a page comment anchors to the page as a whole.","operationId":"V1CommentsController_list","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from a previous response.","schema":{"type":"string"}},{"name":"resolved","required":false,"in":"query","description":"true for resolved only, false for open only; absent for all.","schema":{"type":"boolean"}},{"name":"version_id","required":false,"in":"query","description":"Only comments anchored to that version of this file.","schema":{"type":"string"}},{"name":"format","required":false,"in":"query","description":"csv answers text/csv; limit and cursor are ignored.","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentListDto"}},"text/csv":{"schema":{"type":"string","description":"One header row plus one row per comment and per reply (§ 5)."}}},"description":""},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"List a file’s comments","tags":["Comments"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"post":{"description":"Mention a member with the inline token [@<user_id>]; the response lists the mentions that resolved.","operationId":"V1CommentsController_create","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCommentBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Comment on a file","tags":["Comments"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/files/{fileId}/comments/{commentId}":{"get":{"operationId":"V1CommentsController_retrieve","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}},{"name":"commentId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Retrieve a comment","tags":["Comments"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"patch":{"description":"The author only. Anyone else answers 404.","operationId":"V1CommentsController_update","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}},{"name":"commentId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCommentBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Edit a comment’s text","tags":["Comments"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"delete":{"description":"The author, or an owner or admin of the brandspace. Permanent, and it deletes the comment’s replies.","operationId":"V1CommentsController_remove","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}},{"name":"commentId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Delete a comment","tags":["Comments"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/files/{fileId}/comments/{commentId}/resolve":{"post":{"description":"Anyone who can view the file. Idempotent in effect — send an `Idempotency-Key` to avoid a duplicate event and audit row.","operationId":"V1CommentsController_resolve","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}},{"name":"commentId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Resolve a comment","tags":["Comments"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/files/{fileId}/comments/{commentId}/reopen":{"post":{"description":"Clears resolved_by_id; a reopened comment carries no \"reopened at\".","operationId":"V1CommentsController_reopen","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}},{"name":"commentId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Reopen a comment","tags":["Comments"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/files/{fileId}/comments/{commentId}/replies":{"get":{"description":"Oldest first.","operationId":"V1RepliesController_list","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}},{"name":"commentId","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from a previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplyListDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"List a comment’s replies","tags":["Comments"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"post":{"operationId":"V1RepliesController_create","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}},{"name":"commentId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReplyBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplyDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Reply to a comment","tags":["Comments"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/files/{fileId}/comments/{commentId}/replies/{replyId}":{"patch":{"description":"The author only. Anyone else answers 404.","operationId":"V1RepliesController_update","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}},{"name":"commentId","required":true,"in":"path","schema":{"type":"string"}},{"name":"replyId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateReplyBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplyDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Edit a reply’s text","tags":["Comments"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"delete":{"description":"The author, or an owner or admin of the brandspace. Permanent.","operationId":"V1RepliesController_remove","parameters":[{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}},{"name":"commentId","required":true,"in":"path","schema":{"type":"string"}},{"name":"replyId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Delete a reply","tags":["Comments"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/pages":{"get":{"description":"Pages the key’s creator can see, newest first. Listed by location only: no q, no filter, no kind.","operationId":"V1PagesController_list","parameters":[{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from a previous response.","schema":{"type":"string"}},{"name":"library_id","required":false,"in":"query","schema":{"type":"string"}},{"name":"folder_id","required":false,"in":"query","schema":{"type":"string"}},{"name":"recursive","required":false,"in":"query","description":"Include pages in every descendant folder.","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageListDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"List pages","tags":["Pages"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"post":{"description":"Give exactly one of library_id, folder_id, to_root. blocks becomes the page’s initial content.","operationId":"V1PagesController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePageBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageDetailDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Create a page","tags":["Pages"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/pages/{pageId}":{"get":{"description":"The page plus its content. format=json returns the stored ProseMirror document verbatim; format=markdown renders it. Content is the last stored snapshot: an edit in progress appears after its next save.","operationId":"V1PagesController_retrieve","parameters":[{"name":"pageId","required":true,"in":"path","schema":{"type":"string"}},{"name":"format","required":false,"in":"query","schema":{"type":"string","enum":["json","markdown"],"default":"json"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageDetailDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Retrieve a page","tags":["Pages"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"delete":{"description":"Moves the page to the trash. permanent=true deletes it and its comments irreversibly.","operationId":"V1PagesController_remove","parameters":[{"name":"pageId","required":true,"in":"path","schema":{"type":"string"}},{"name":"permanent","required":false,"in":"query","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Trash or permanently delete a page","tags":["Pages"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/pages/{pageId}/publish":{"post":{"description":"Anyone holding the page’s public_url can read it. Idempotent in effect — send an `Idempotency-Key` to avoid a duplicate event and audit row.","operationId":"V1PagesController_publish","parameters":[{"name":"pageId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageDetailDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Publish a page","tags":["Pages"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/pages/{pageId}/unpublish":{"post":{"description":"Withdraws the public URL. Idempotent in effect — send an `Idempotency-Key` to avoid a duplicate event and audit row.","operationId":"V1PagesController_unpublish","parameters":[{"name":"pageId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageDetailDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Unpublish a page","tags":["Pages"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/pages/{pageId}/blocks":{"post":{"description":"Appends at the end of the live document, through the collaboration server, so open editors receive it immediately. Not naturally idempotent — send an Idempotency-Key. Answers 503 if the server has not persisted within 5 seconds; re-read the page before retrying. A page whose collaborative document was never initialized (seeded, or created outside this API, and never opened in the editor) answers 409 page_not_initialized: open it once in the editor, then retry.","operationId":"V1PagesController_appendBlocks","parameters":[{"name":"pageId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppendBlocksBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageDetailDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Append blocks to a page","tags":["Pages"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/shared-links":{"get":{"description":"The brandspace’s links, newest first. File-scoped links are not included — the internal listing excludes them.","operationId":"V1SharedLinksController_list","parameters":[{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from a previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedLinkListDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"List shared links","tags":["Shared links"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"post":{"description":"One call: target, access, password, expiry, anonymous comments and (for a board) the views. If a later step fails the link is deleted again and the failure is returned.","operationId":"V1SharedLinksController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSharedLinkBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedLinkDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Create a shared link","tags":["Shared links"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/shared-links/{sharedLinkId}":{"get":{"operationId":"V1SharedLinksController_retrieve","parameters":[{"name":"sharedLinkId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedLinkDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Retrieve a shared link","tags":["Shared links"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"patch":{"description":"Fields are applied in a fixed order and the first failure stops the sequence — the fields already applied stay applied. Re-read the link to see its state.","operationId":"V1SharedLinksController_update","parameters":[{"name":"sharedLinkId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSharedLinkBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedLinkDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Update a shared link","tags":["Shared links"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"delete":{"description":"Permanent. Visitors holding the URL lose access at once.","operationId":"V1SharedLinksController_remove","parameters":[{"name":"sharedLinkId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Delete a shared link","tags":["Shared links"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/transfers":{"post":{"description":"Send Brault files and folders to finish in one call, and/or declare uploads to finish later with the upload routes. Send at least one of files, folders or uploads.","operationId":"V1TransfersController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTransferBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferCreatedDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Create a transfer","tags":["Transfers"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"get":{"description":"The brandspace’s transfers, newest first, with any open drafts interleaved by creation time.","operationId":"V1TransfersController_list","parameters":[{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from a previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferListDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"List transfers","tags":["Transfers"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/transfers/{transferId}/uploads/{uploadId}/parts":{"post":{"operationId":"V1TransfersController_parts","parameters":[{"name":"transferId","required":true,"in":"path","schema":{"type":"string"}},{"name":"uploadId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadPartsBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadPartsDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Get presigned URLs for multipart parts","tags":["Transfers"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/transfers/{transferId}/uploads/{uploadId}/complete":{"post":{"description":"Send `parts` for a multipart upload. For a single PUT the server checks the object itself.","operationId":"V1TransfersController_completeUpload","parameters":[{"name":"transferId","required":true,"in":"path","schema":{"type":"string"}},{"name":"uploadId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteUploadBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferUploadStatusDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Finish one declared upload","tags":["Transfers"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/transfers/{transferId}/complete":{"post":{"description":"Every declared upload must be completed first. The transfer’s link works from this moment.","operationId":"V1TransfersController_complete","parameters":[{"name":"transferId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferDetailDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Finalize a transfer","tags":["Transfers"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/transfers/{transferId}":{"get":{"description":"With its files and folders, and a fresh zip URL.","operationId":"V1TransfersController_retrieve","parameters":[{"name":"transferId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferDetailDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Retrieve a transfer","tags":["Transfers"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"patch":{"description":"Set or clear the password, and/or move the expiry. Expiry days count from today.","operationId":"V1TransfersController_update","parameters":[{"name":"transferId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTransferBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Update a transfer","tags":["Transfers"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"delete":{"description":"Recipients lose access at once. An open draft is canceled and its uploads released instead.","operationId":"V1TransfersController_remove","parameters":[{"name":"transferId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Expire a transfer","tags":["Transfers"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/boards":{"get":{"description":"Boards of the brandspace the key’s creator can see: every board when their role carries boards.manage_all, otherwise only the boards they were granted. Pinned boards first, then the board’s own position.","operationId":"V1BoardsController_list","parameters":[{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from a previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardListDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"List boards","tags":["Boards"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"post":{"operationId":"V1BoardsController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBoardBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardDetailDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Create a board","tags":["Boards"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/boards/{boardId}":{"get":{"description":"The board plus its properties and their options.","operationId":"V1BoardsController_retrieve","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardDetailDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Retrieve a board","tags":["Boards"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"patch":{"description":"name, color and emoji are applied first; pinned is applied after them. Only the fields sent change.","operationId":"V1BoardsController_update","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBoardBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardDetailDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Update a board","tags":["Boards"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"delete":{"description":"Permanent: there is no trash for boards. The board’s properties, options, memberships and values go with it; the files themselves are untouched.","operationId":"V1BoardsController_remove","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Delete a board","tags":["Boards"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/boards/{boardId}/members":{"get":{"description":"User ids only: everyone with an explicit grant plus everyone whose brandspace role carries boards.manage_all. Resolve a name or email with GET /v1/members/{userId} (members:read). Single page.","operationId":"V1BoardsController_members","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardMemberListDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"List board members","tags":["Boards"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/boards/{boardId}/properties":{"get":{"description":"In position order, each with its options.","operationId":"V1BoardPropertiesController_list","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from a previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyListDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"List board properties","tags":["Boards"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"post":{"operationId":"V1BoardPropertiesController_create","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBoardPropertyBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Create a board property","tags":["Boards"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/boards/{boardId}/properties/{propertyId}":{"get":{"operationId":"V1BoardPropertiesController_retrieve","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string"}},{"name":"propertyId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Retrieve a board property","tags":["Boards"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"patch":{"description":"A property’s type and position are fixed.","operationId":"V1BoardPropertiesController_update","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string"}},{"name":"propertyId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBoardPropertyBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Rename a board property","tags":["Boards"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"delete":{"description":"Its options and every value files hold for it go with it.","operationId":"V1BoardPropertiesController_remove","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string"}},{"name":"propertyId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Delete a board property","tags":["Boards"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/boards/{boardId}/properties/{propertyId}/options":{"post":{"description":"`status` and `multi_tag` properties only.","operationId":"V1BoardPropertiesController_createOption","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string"}},{"name":"propertyId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOptionBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Create an option","tags":["Boards"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/boards/{boardId}/properties/{propertyId}/options/{optionId}":{"patch":{"operationId":"V1BoardPropertiesController_updateOption","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string"}},{"name":"propertyId","required":true,"in":"path","schema":{"type":"string"}},{"name":"optionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOptionBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Update an option","tags":["Boards"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"delete":{"description":"Clears it from every file’s value: a status value pointing at it becomes unset, a multi_tag value loses that tag.","operationId":"V1BoardPropertiesController_removeOption","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string"}},{"name":"propertyId","required":true,"in":"path","schema":{"type":"string"}},{"name":"optionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Delete an option","tags":["Boards"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/boards/{boardId}/query":{"post":{"description":"A read expressed as POST because its filter is a JSON document. Returns board_file objects: the file, this board’s values for it, and when it was added. Trashed files are never listed.","operationId":"V1BoardFilesController_query","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryBoardFilesBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardFileListDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Query the files on a board","tags":["Boards"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/boards/{boardId}/files":{"post":{"description":"Every id is either added or already on the board. An id this key cannot serve fails the whole request with 404 before anything is added.","operationId":"V1BoardFilesController_addFiles","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddBoardFilesBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardFilesBatchDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Add files to a board","tags":["Boards"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/boards/{boardId}/files/{fileId}":{"delete":{"description":"Removes the membership and this board’s values for the file. The file itself stays where it lives. A file that is not on the board answers 404.","operationId":"V1BoardFilesController_removeFile","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string"}},{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Remove a file from a board","tags":["Boards"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/boards/{boardId}/files/{fileId}/properties/{propertyId}":{"put":{"description":"Send exactly one field, named after the property’s type. `null` clears a scalar; multi_tag takes { add, remove }.","operationId":"V1BoardFilesController_setValue","parameters":[{"name":"boardId","required":true,"in":"path","schema":{"type":"string"}},{"name":"fileId","required":true,"in":"path","schema":{"type":"string"}},{"name":"propertyId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetBoardValueBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BoardFileDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Set or clear a board property value","tags":["Boards"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/properties":{"get":{"description":"In position order, each with its options.","operationId":"V1PropertiesController_list","parameters":[{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from a previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyListDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"List brandspace properties","tags":["Properties"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"post":{"operationId":"V1PropertiesController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBrandspacePropertyBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Create a brandspace property","tags":["Properties"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/properties/{propertyId}":{"get":{"operationId":"V1PropertiesController_retrieve","parameters":[{"name":"propertyId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Retrieve a brandspace property","tags":["Properties"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"patch":{"operationId":"V1PropertiesController_update","parameters":[{"name":"propertyId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBrandspacePropertyBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Update a brandspace property","tags":["Properties"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"delete":{"description":"Its options and every value files hold for it go with it.","operationId":"V1PropertiesController_remove","parameters":[{"name":"propertyId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Delete a brandspace property","tags":["Properties"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/properties/{propertyId}/options":{"post":{"description":"`tag` properties only.","operationId":"V1PropertiesController_createOption","parameters":[{"name":"propertyId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBrandspaceOptionBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Create an option","tags":["Properties"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/properties/{propertyId}/options/{optionId}":{"patch":{"operationId":"V1PropertiesController_updateOption","parameters":[{"name":"propertyId","required":true,"in":"path","schema":{"type":"string"}},{"name":"optionId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBrandspaceOptionBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Update an option","tags":["Properties"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"delete":{"operationId":"V1PropertiesController_removeOption","parameters":[{"name":"propertyId","required":true,"in":"path","schema":{"type":"string"}},{"name":"optionId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Delete an option","tags":["Properties"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/search":{"get":{"description":"Keyword, semantic and natural-language search over everything the key’s creator can see. Consumes the search rate bucket on every call.","operationId":"V1SearchController_search","parameters":[{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from a previous response.","schema":{"type":"string"}},{"name":"q","required":true,"in":"query","description":"Keyword and natural-language query.","schema":{"maxLength":500,"type":"string"}},{"name":"scope","required":false,"in":"query","description":"`brandspace`, `library:<library_id>` or `folder:<folder_id>`.","schema":{"pattern":"^(brandspace|library:[A-Za-z0-9_-]{1,64}|folder:[A-Za-z0-9_-]{1,64})$","default":"brandspace","example":"library:clx1abc","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResultsDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Search files and folders","tags":["Search"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/members":{"get":{"description":"Members of the brandspace with their role. Includes email — that is what the members:read scope buys.","operationId":"V1MembersController_list","parameters":[{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from a previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemberListDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"List members","tags":["Brandspace"],"x-brault-plane":"central","servers":[{"url":"https://api.brault.app"}]}},"/v1/members/{userId}":{"get":{"operationId":"V1MembersController_retrieve","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemberDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Retrieve a member","tags":["Brandspace"],"x-brault-plane":"central","servers":[{"url":"https://api.brault.app"}]}},"/v1/roles":{"get":{"operationId":"V1MembersController_listRoles","parameters":[{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from a previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleListDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"List roles","tags":["Brandspace"],"x-brault-plane":"central","servers":[{"url":"https://api.brault.app"}]}},"/v1/brandspace":{"get":{"description":"Available to every key, whatever its scopes. The id is always the key’s own.","operationId":"V1BrandspaceController_retrieve","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandspaceDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Retrieve the brandspace this key belongs to","tags":["Brandspace"],"x-brault-plane":"central","servers":[{"url":"https://api.brault.app"}]}},"/v1/webhooks":{"get":{"description":"Every endpoint of the brandspace, newest first. `secret` is null on every row.","operationId":"V1WebhooksController_list","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookListDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"List webhook endpoints","tags":["Webhooks"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"post":{"description":"The response carries the signing secret. It is shown here and once more on roll-secret, and can never be read back. Sending an Idempotency-Key caches this response — the secret included — for 24 h; omit the header if you do not want that.","operationId":"V1WebhooksController_create","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Create a webhook endpoint","tags":["Webhooks"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/webhooks/{webhookId}":{"get":{"operationId":"V1WebhooksController_retrieve","parameters":[{"name":"webhookId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Retrieve a webhook endpoint","tags":["Webhooks"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"patch":{"description":"Send any of url, name, events or status. `events` replaces the list. Setting status to disabled is a 409: only the system disables an endpoint.","operationId":"V1WebhooksController_update","parameters":[{"name":"webhookId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookBodyDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Update a webhook endpoint","tags":["Webhooks"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]},"delete":{"description":"Soft delete. Pending deliveries are cancelled and the endpoint stops receiving events at once.","operationId":"V1WebhooksController_remove","parameters":[{"name":"webhookId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletedDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Delete a webhook endpoint","tags":["Webhooks"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/webhooks/{webhookId}/test":{"post":{"description":"Delivers a synthetic webhook.test event inline and returns the resulting delivery. One attempt, no retry, no effect on the endpoint’s failure counters, and it works on any status including disabled. Worst-case latency is the 5 s attempt timeout plus DNS. A failed test is a 200 with a delivery whose status is exhausted, not an error. DO NOT send an Idempotency-Key: a repeat inside 24 h would replay the first attempt’s delivery without sending anything.","operationId":"V1WebhooksController_test","parameters":[{"name":"webhookId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Send a test delivery","tags":["Webhooks"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/webhooks/{webhookId}/roll-secret":{"post":{"description":"Returns a new secret and keeps the previous one valid for 24 h, during which every delivery carries two v1 signature entries, current first. A second roll inside that window is a 409 with details.retry_after. Sending an Idempotency-Key caches this response — the secret included — for 24 h.","operationId":"V1WebhooksController_rollSecret","parameters":[{"name":"webhookId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Roll the signing secret","tags":["Webhooks"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/webhooks/{webhookId}/deliveries":{"get":{"description":"Newest first, optionally filtered by status. The cursor is opaque; do not construct one. At most the last 10,000 deliveries of an endpoint are kept, and none older than 30 days.","operationId":"V1WebhooksController_deliveries","parameters":[{"name":"webhookId","required":true,"in":"path","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Opaque cursor from a previous response.","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["pending","success","failed","exhausted","parked"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryListDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"List an endpoint’s deliveries","tags":["Webhooks"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/webhooks/{webhookId}/deliveries/{deliveryId}":{"get":{"operationId":"V1WebhooksController_delivery","parameters":[{"name":"webhookId","required":true,"in":"path","schema":{"type":"string"}},{"name":"deliveryId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Retrieve one delivery","tags":["Webhooks"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/webhooks/{webhookId}/deliveries/{deliveryId}/redeliver":{"post":{"description":"Queues a NEW delivery for the same event: attempt restarts at 1, origin is \"redeliver\" and replayed_from_id names the row it came from. The source row is not touched. Brault-Event-Id is unchanged, so a receiver deduplicating on it — as this API has always asked — sees a duplicate and drops it. Allowed only when the source delivery is success or exhausted, is not a webhook.test row, the endpoint is active, and the event payload is still inside the 30-day window.","operationId":"V1WebhooksController_redeliver","parameters":[{"name":"webhookId","required":true,"in":"path","schema":{"type":"string"}},{"name":"deliveryId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Redeliver one delivery","tags":["Webhooks"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}},"/v1/webhooks/{webhookId}/replays":{"post":{"description":"Queues one pending delivery per event of the brandspace that occurred in [from, to) and whose type this endpoint subscribes to now, skipping events it already delivered successfully unless include_delivered is true. The window is at most 7 days and must lie inside the 30-day event window; a call may match at most 10,000 events. Both bounds are refusals, never truncations, so a replay is never silently partial. webhook.test events are never replayed. Sending an Idempotency-Key caches this report for 24 h without replaying twice.","operationId":"V1WebhooksController_replay","parameters":[{"name":"webhookId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplayBodyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplayDto"}}}},"default":{"description":"Error — see conventions.md § Errors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1ErrorDto"}}}}},"security":[{"apiKey":[]}],"summary":"Replay a window of events","tags":["Webhooks"],"x-brault-plane":"regional","servers":[{"url":"https://{region}.api.brault.app","variables":{"region":{"default":"us","enum":["us"]}}}]}}},"info":{"title":"Brault Public API","description":"Automate libraries, files, boards, pages, reviews and sharing in your brandspace.","version":"1.0.0","contact":{}},"tags":[{"name":"Meta","description":"Who the key is, what it is allowed to do, and how much of its budget is left."},{"name":"Brandspace","description":"The brandspace behind the key, its members and its roles."},{"name":"Libraries","description":"Top-level containers. Called workspaces inside the product database."},{"name":"Folders","description":"Folders inside a library."},{"name":"Files","description":"The central resource: metadata, renditions, moves, copies and deletion."},{"name":"Boards","description":"Boards, the files on them, their properties and options."},{"name":"Properties","description":"Brandspace properties and options — the schema of the metadata layer."},{"name":"Comments","description":"Comments and replies on a file, with a CSV export."},{"name":"Pages","description":"Pages: structured documents, published or private."},{"name":"Shared links","description":"Public links to a file, folder, library or board."},{"name":"Uploads","description":"Three-call presigned upload flow. Bytes go straight to S3."},{"name":"Downloads","description":"Signed URLs for one file, and asynchronous ZIP downloads."},{"name":"Versions","description":"Version history of a file."},{"name":"Search","description":"Keyword, semantic and natural-language search."},{"name":"Imports","description":"Import a file into the brandspace from a public URL."},{"name":"Webhooks","description":"Webhook endpoints and their deliveries."},{"name":"Transfers","description":"Send files and folders as a BTransfer, and manage the ones already sent."}],"servers":[{"url":"https://api.brault.app"}],"components":{"securitySchemes":{"apiKey":{"scheme":"bearer","bearerFormat":"bsk_…","type":"http","description":"API key from Settings → Developers"}},"schemas":{"V1ErrorDto":{"type":"object","properties":{"object":{"type":"string","example":"error"},"status":{"type":"number","example":404},"code":{"type":"string","example":"not_found"},"message":{"type":"string"},"request_id":{"type":"string","example":"req_a1b2c3"},"details":{"type":"object"}},"required":["object","status","code","message","request_id"]},"HealthDto":{"type":"object","properties":{"object":{"type":"string","example":"health"},"status":{"type":"string","example":"ok"},"time":{"type":"string","format":"date-time"}},"required":["object","status","time"]},"BrandspaceRefDto":{"type":"object","properties":{"id":{"type":"string","example":"clx1…"},"name":{"type":"string","example":"Acme Studio"},"username":{"type":"string","example":"acme","description":"Subdomain of the brandspace"},"region":{"type":"string","example":"us","description":"Authoritative. The region that serves this brandspace’s content, and therefore the one whose host may answer a regional path."}},"required":["id","name","username","region"]},"KeyRefDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"display":{"type":"string","example":"bsk_us_a1b2c3d4_…wxyz","description":"The masked key, byte-identical in shape to the string you hold: `bsk_<region>_<prefix8>_…<last4>` when it carries a region, `bsk_<prefix8>_…<last4>` when it does not."},"scopes":{"example":["files:read"],"type":"array","items":{"type":"string"}},"region":{"type":"string","nullable":true,"example":"us","description":"The region the key STRING declares, or null for a key minted before regions existed. Advisory: it says which host to dial, never which host may answer."},"region_stale":{"type":"boolean","description":"True when the key declares a region and it is not the brandspace’s — the brandspace moved after the key was minted. The key still works, on the brandspace’s host; the printed hint is what is out of date."},"expires_at":{"type":"string","format":"date-time","nullable":true}},"required":["id","name","display","scopes","region","region_stale","expires_at"]},"UserRefDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"PlanRefDto":{"type":"object","properties":{"type":{"type":"string","example":"pro"},"name":{"type":"string","example":"Pro"}},"required":["type","name"]},"LimitsDto":{"type":"object","properties":{"burst_per_second":{"type":"number"},"sustained_per_minute":{"type":"number"},"monthly_requests":{"type":"number"},"uploads_per_day":{"type":"number"},"downloads_per_day":{"type":"number"},"search_per_minute":{"type":"number"}},"required":["burst_per_second","sustained_per_minute","monthly_requests","uploads_per_day","downloads_per_day","search_per_minute"]},"HostsDto":{"type":"object","properties":{"central":{"type":"string","example":"https://api.brault.app","description":"Base URL of the central plane."},"regional":{"type":"string","example":"https://us.api.brault.app","description":"Base URL of the host that answers this brandspace’s regional paths, derived from its region."}},"required":["central","regional"]},"ApiKeyContextDto":{"type":"object","properties":{"object":{"type":"string","example":"api_key_context"},"brandspace":{"$ref":"#/components/schemas/BrandspaceRefDto"},"key":{"$ref":"#/components/schemas/KeyRefDto"},"created_by":{"$ref":"#/components/schemas/UserRefDto"},"plan":{"$ref":"#/components/schemas/PlanRefDto"},"limits":{"$ref":"#/components/schemas/LimitsDto"},"hosts":{"$ref":"#/components/schemas/HostsDto"}},"required":["object","brandspace","key","created_by","plan","limits","hosts"]},"WindowUsageDto":{"type":"object","properties":{"limit":{"type":"number"},"used":{"type":"number"},"remaining":{"type":"number"},"resets_at":{"type":"string","format":"date-time"}},"required":["limit","used","remaining","resets_at"]},"UsageDto":{"type":"object","properties":{"object":{"type":"string","example":"usage"},"sustained":{"$ref":"#/components/schemas/WindowUsageDto"},"month":{"$ref":"#/components/schemas/WindowUsageDto"},"search":{"$ref":"#/components/schemas/WindowUsageDto"},"uploads":{"$ref":"#/components/schemas/WindowUsageDto"},"downloads":{"$ref":"#/components/schemas/WindowUsageDto"}},"required":["object","sustained","month","search","uploads","downloads"]},"WebhookEventActorDto":{"type":"object","properties":{"type":{"type":"string","enum":["user","api_key","system","anonymous"]},"id":{"type":"string","nullable":true,"description":"null for system and anonymous."}},"required":["type","id"]},"WebhookEventDto":{"type":"object","properties":{"id":{"type":"string","example":"evt_c0ffee","description":"The deduplication key: identical across every attempt and endpoint."},"object":{"type":"string","example":"event"},"type":{"type":"string","example":"file.created"},"occurred_at":{"type":"string","format":"date-time","description":"When the change happened, not when the delivery ran."},"brandspace_id":{"type":"string"},"actor":{"$ref":"#/components/schemas/WebhookEventActorDto"},"data":{"type":"object","additionalProperties":true,"description":"A minimal snapshot: ids, names and locations only. Its `object` field names the shape — see `data_object` on GET /v1/events."},"attempt":{"type":"number","minimum":1,"maximum":8}},"required":["id","object","type","occurred_at","brandspace_id","actor","data","attempt"]},"EventTypeDto":{"type":"object","properties":{"object":{"type":"string","example":"event_type"},"type":{"type":"string","description":"The token to put in a webhook’s `events`."},"group":{"type":"string","enum":["files","folders","boards","properties","comments","pages","sharing","members","imports","transfers","platform"],"description":"The grouping a picker renders."},"description":{"type":"string"},"data_object":{"type":"string","description":"The `object` value of this event’s `data`, e.g. \"file\"."}},"required":["object","type","group","description","data_object"]},"EventTypeListDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/EventTypeDto"}}},"required":["object","has_more","next_cursor","data"]},"LibraryDto":{"type":"object","properties":{"object":{"type":"string","example":"library"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"emoji":{"type":"string","nullable":true},"pinned":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"string"}},"required":["object","id","name","description","emoji","pinned","created_at","updated_at","created_by_id"]},"LibraryListDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/LibraryDto"}}},"required":["object","has_more","next_cursor","data"]},"CreateLibraryBodyDto":{"type":"object","properties":{"name":{"type":"string","maxLength":256},"description":{"type":"string","maxLength":500},"emoji":{"type":"string","maxLength":50,"description":"Emoji shown next to the library name."}},"required":["name"]},"LibraryDetailDto":{"type":"object","properties":{"object":{"type":"string","example":"library"},"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"emoji":{"type":"string","nullable":true},"pinned":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"string"},"files_count":{"type":"number"},"folders_count":{"type":"number"},"total_size":{"type":"number","description":"Total size of the library in bytes."}},"required":["object","id","name","description","emoji","pinned","created_at","updated_at","created_by_id","files_count","folders_count","total_size"]},"UpdateLibraryBodyDto":{"type":"object","properties":{"name":{"type":"string","maxLength":256},"description":{"type":"string","maxLength":500}}},"DeletedDto":{"type":"object","properties":{"object":{"type":"string","example":"deleted"},"id":{"type":"string"},"deleted":{"type":"boolean","example":true}},"required":["object","id","deleted"]},"FolderDto":{"type":"object","properties":{"object":{"type":"string","example":"folder"},"id":{"type":"string"},"name":{"type":"string"},"library_id":{"type":"string"},"parent_id":{"type":"string","nullable":true},"color":{"type":"string","example":"#676666"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"string"},"trashed_at":{"type":"string","format":"date-time","nullable":true}},"required":["object","id","name","library_id","parent_id","color","created_at","updated_at","created_by_id","trashed_at"]},"FolderListDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/FolderDto"}}},"required":["object","has_more","next_cursor","data"]},"CreateFolderBodyDto":{"type":"object","properties":{"name":{"type":"string","maxLength":256},"library_id":{"type":"string","description":"Library for a root folder. Exactly one of `library_id`, `folder_id`."},"folder_id":{"type":"string","description":"Parent folder. Exactly one of `library_id`, `folder_id`; the library is the parent's."}},"required":["name"]},"FolderDetailDto":{"type":"object","properties":{"object":{"type":"string","example":"folder"},"id":{"type":"string"},"name":{"type":"string"},"library_id":{"type":"string"},"parent_id":{"type":"string","nullable":true},"color":{"type":"string","example":"#676666"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"string"},"trashed_at":{"type":"string","format":"date-time","nullable":true},"files_count":{"type":"number"},"folders_count":{"type":"number"},"total_size":{"type":"number"}},"required":["object","id","name","library_id","parent_id","color","created_at","updated_at","created_by_id","trashed_at","files_count","folders_count","total_size"]},"UpdateFolderBodyDto":{"type":"object","properties":{"name":{"type":"string","maxLength":256},"color":{"type":"string","example":"#676666"}}},"MoveFolderBodyDto":{"type":"object","properties":{"library_id":{"type":"string","description":"Destination library."},"folder_id":{"type":"string","description":"Destination folder."}}},"StartImportBodyDto":{"type":"object","properties":{"url":{"type":"string","description":"Public http(s) URL of the file to import.","maxLength":2048},"name":{"type":"string","description":"Name for the imported file. Defaults to the source filename."},"library_id":{"type":"string","description":"Library to import into. Exactly one of `library_id`, `folder_id`."},"folder_id":{"type":"string","description":"Folder to import into. Exactly one of `library_id`, `folder_id`."}},"required":["url"]},"ImportDto":{"type":"object","properties":{"object":{"type":"string","example":"import"},"id":{"type":"string"},"status":{"type":"string","enum":["queued","running","succeeded","failed"]},"source_url":{"type":"string","description":"The resolved URL, after redirects."},"file_id":{"type":"string","nullable":true,"description":"Set once `status` is `succeeded`."},"bytes_total":{"type":"number","nullable":true,"description":"From the source's declared Content-Length."},"bytes_written":{"type":"number","nullable":true},"error_code":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","nullable":true}},"required":["object","id","status","source_url","file_id","bytes_total","bytes_written","error_code","created_at","finished_at"]},"FileVersionSummaryDto":{"type":"object","properties":{"count":{"type":"number"},"active_number":{"type":"number","nullable":true},"active_id":{"type":"string","nullable":true,"description":"Only present on a single-file read."}},"required":["count","active_number","active_id"]},"FileDto":{"type":"object","properties":{"object":{"type":"string","example":"file"},"id":{"type":"string"},"kind":{"type":"string","enum":["image","video","audio","document","link","other"]},"name":{"type":"string"},"extension":{"type":"string"},"mime":{"type":"string"},"size":{"type":"number","description":"Bytes."},"status":{"type":"string","enum":["processing","processed","failed"]},"library_id":{"type":"string","nullable":true},"folder_id":{"type":"string","nullable":true},"external_url":{"type":"string","nullable":true},"duration_ms":{"type":"number","nullable":true,"description":"Milliseconds, for audio and video."},"resolution":{"type":"string","nullable":true,"example":"1920x1080"},"created_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"string","nullable":true},"trashed_at":{"type":"string","format":"date-time","nullable":true},"thumbnail_url":{"type":"string","nullable":true,"description":"Signed for 15 minutes."},"version":{"$ref":"#/components/schemas/FileVersionSummaryDto"}},"required":["object","id","kind","name","extension","mime","size","status","library_id","folder_id","external_url","duration_ms","resolution","created_at","created_by_id","trashed_at","thumbnail_url","version"]},"FileListDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/FileDto"}}},"required":["object","has_more","next_cursor","data"]},"FileRenditionsDto":{"type":"object","properties":{"thumbnail_url":{"type":"string","nullable":true},"preview_url":{"type":"string","nullable":true},"frames_url":{"type":"string","nullable":true},"scrub_url":{"type":"string","nullable":true}},"required":["thumbnail_url","preview_url","frames_url","scrub_url"]},"StatusValueDto":{"type":"object","properties":{"option_id":{"type":"string"}},"required":["option_id"]},"PersonValueDto":{"type":"object","properties":{"user_id":{"type":"string"}},"required":["user_id"]},"DateValueDto":{"type":"object","properties":{"start":{"type":"string","format":"date-time"}},"required":["start"]},"TagValueItemDto":{"type":"object","properties":{"option_id":{"type":"string"}},"required":["option_id"]},"PropertyValueDto":{"type":"object","properties":{"property_id":{"type":"string"},"type":{"type":"string","enum":["status","person","date","checkbox","text","multi_tag","tag"]},"status":{"$ref":"#/components/schemas/StatusValueDto"},"person":{"$ref":"#/components/schemas/PersonValueDto"},"date":{"$ref":"#/components/schemas/DateValueDto"},"checkbox":{"type":"boolean"},"text":{"type":"string"},"multi_tag":{"type":"array","items":{"$ref":"#/components/schemas/TagValueItemDto"}},"tag":{"type":"array","items":{"$ref":"#/components/schemas/TagValueItemDto"}}},"required":["property_id","type"]},"FileDetailDto":{"type":"object","properties":{"object":{"type":"string","example":"file"},"id":{"type":"string"},"kind":{"type":"string","enum":["image","video","audio","document","link","other"]},"name":{"type":"string"},"extension":{"type":"string"},"mime":{"type":"string"},"size":{"type":"number","description":"Bytes."},"status":{"type":"string","enum":["processing","processed","failed"]},"library_id":{"type":"string","nullable":true},"folder_id":{"type":"string","nullable":true},"external_url":{"type":"string","nullable":true},"duration_ms":{"type":"number","nullable":true,"description":"Milliseconds, for audio and video."},"resolution":{"type":"string","nullable":true,"example":"1920x1080"},"created_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"string","nullable":true},"trashed_at":{"type":"string","format":"date-time","nullable":true},"thumbnail_url":{"type":"string","nullable":true,"description":"Signed for 15 minutes."},"version":{"$ref":"#/components/schemas/FileVersionSummaryDto"},"updated_at":{"type":"string","format":"date-time"},"tags":{"type":"array","items":{"type":"string"}},"published":{"type":"boolean"},"renditions":{"$ref":"#/components/schemas/FileRenditionsDto"},"properties":{"description":"Brandspace property values set on this file. Only properties with a value appear; list items never carry this.","type":"array","items":{"$ref":"#/components/schemas/PropertyValueDto"}}},"required":["object","id","kind","name","extension","mime","size","status","library_id","folder_id","external_url","duration_ms","resolution","created_at","created_by_id","trashed_at","thumbnail_url","version","updated_at","tags","published","renditions","properties"]},"FileDownloadDto":{"type":"object","properties":{"object":{"type":"string","example":"file_download"},"file_id":{"type":"string"},"rendition":{"type":"string","enum":["original","preview","thumbnail"]},"url":{"type":"string","description":"Signed URL, valid for 15 minutes."},"expires_at":{"type":"string","format":"date-time"}},"required":["object","file_id","rendition","url","expires_at"]},"SimilarFilesDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/FileDto"}}},"required":["object","has_more","next_cursor","data"]},"UpdateFileBodyDto":{"type":"object","properties":{"name":{"type":"string","maxLength":256},"tags":{"description":"Replaces the file’s tags entirely.","type":"array","items":{"type":"string"}},"external_url":{"type":"string","description":"Target URL of a `link` file."}}},"MoveBodyDto":{"type":"object","properties":{"library_id":{"type":"string","description":"Destination library."},"folder_id":{"type":"string","description":"Destination folder."},"to_root":{"type":"boolean","description":"Move to the brandspace root (\"All files\")."}}},"TagWriteDto":{"type":"object","properties":{"add":{"maxItems":50,"type":"array","items":{"type":"string"}},"remove":{"maxItems":50,"type":"array","items":{"type":"string"}}}},"DateValueInputDto":{"type":"object","properties":{"start":{"type":"string","description":"`YYYY-MM-DD` (taken as UTC midnight) or an ISO 8601 instant."}},"required":["start"]},"PersonValueInputDto":{"type":"object","properties":{"user_id":{"type":"string","description":"A user who can see this board."}},"required":["user_id"]},"SetBrandspaceValueBodyDto":{"type":"object","properties":{"tag":{"description":"Add and/or remove options. There is no null form for a tag list — remove them all instead.","allOf":[{"$ref":"#/components/schemas/TagWriteDto"}]},"text":{"type":"string","nullable":true,"maxLength":600,"description":"`null` clears the value."},"date":{"nullable":true,"description":"`null` clears the value.","type":"object","allOf":[{"$ref":"#/components/schemas/DateValueInputDto"}]},"checkbox":{"type":"boolean","nullable":true,"description":"`null` clears the value."},"person":{"nullable":true,"description":"`null` clears the value.","type":"object","allOf":[{"$ref":"#/components/schemas/PersonValueInputDto"}]}}},"BoardDto":{"type":"object","properties":{"object":{"type":"string","example":"board"},"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","example":"#E2E8EE"},"emoji":{"type":"string","nullable":true},"logo_url":{"type":"string","nullable":true,"description":"Public CDN URL of the uploaded logo; null when the board uses an emoji or nothing."},"pinned":{"type":"boolean"},"my_access":{"type":"string","enum":["view","edit","manage"],"description":"The key creator’s own level on this board."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"string","nullable":true}},"required":["object","id","name","color","emoji","logo_url","pinned","my_access","created_at","updated_at","created_by_id"]},"FileBoardsListDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/BoardDto"}}},"required":["object","has_more","next_cursor","data"]},"CreateDownloadBodyDto":{"type":"object","properties":{"file_ids":{"type":"array","items":{"type":"string"}},"folder_ids":{"type":"array","items":{"type":"string"}},"renditions":{"type":"array","default":["original"],"items":{"type":"string","enum":["original","preview","thumbnail"]}}}},"DownloadDto":{"type":"object","properties":{"object":{"type":"string","example":"download"},"id":{"type":"string"},"status":{"type":"string","enum":["queued","zipping","ready","failed","canceled","expired"]},"progress":{"type":"number","description":"0..100"},"object_count":{"type":"number"},"url":{"type":"string","nullable":true,"description":"Signed ZIP URL, present once ready."},"size":{"type":"number","nullable":true,"description":"ZIP size in bytes, once known."},"error_code":{"type":"string","nullable":true}},"required":["object","id","status","progress","object_count","url","size","error_code"]},"StartUploadBodyDto":{"type":"object","properties":{"name":{"type":"string","maxLength":256},"size":{"type":"number","description":"Bytes. Required — the backend reserves and validates against it. At most 5 TiB (S3’s object ceiling).","maximum":5497558138880},"library_id":{"type":"string","description":"Library to upload into. Exactly one of `library_id`, `folder_id`, `file_id`."},"folder_id":{"type":"string","description":"Folder to upload into. Exactly one of `library_id`, `folder_id`, `file_id`."},"file_id":{"type":"string","description":"Upload a new VERSION of this file instead of creating one."},"to_root":{"type":"boolean","description":"Not supported on v1; sending `true` is rejected."}},"required":["name","size"]},"UploadDto":{"type":"object","properties":{"object":{"type":"string","example":"upload"},"id":{"type":"string"},"method":{"type":"string","enum":["put","multipart"]},"file_id":{"type":"string"},"version_id":{"type":"string","nullable":true,"description":"Version being created, for a version upload."},"upload_url":{"type":"string","nullable":true,"description":"PUT the bytes here. Null for a multipart upload."},"part_size":{"type":"number","nullable":true,"description":"Bytes per part, for a multipart upload."},"part_count":{"type":"number","nullable":true},"expires_at":{"type":"string","format":"date-time"}},"required":["object","id","method","file_id","version_id","upload_url","part_size","part_count","expires_at"]},"UploadPartsBodyDto":{"type":"object","properties":{"part_numbers":{"maxItems":1000,"description":"Each 1–10000 (§2.9), no duplicates.","type":"array","items":{"type":"number"}}},"required":["part_numbers"]},"UploadPartDto":{"type":"object","properties":{"part_number":{"type":"number"},"upload_url":{"type":"string"}},"required":["part_number","upload_url"]},"UploadPartsDto":{"type":"object","properties":{"object":{"type":"string","example":"upload_parts"},"parts":{"type":"array","items":{"$ref":"#/components/schemas/UploadPartDto"}}},"required":["object","parts"]},"CompletePartDto":{"type":"object","properties":{"part_number":{"type":"number"},"etag":{"type":"string","description":"ETag S3 returned for this part."}},"required":["part_number","etag"]},"CompleteUploadBodyDto":{"type":"object","properties":{"parts":{"description":"Required for a multipart upload.","type":"array","items":{"$ref":"#/components/schemas/CompletePartDto"}}}},"AbortedDto":{"type":"object","properties":{"object":{"type":"string","example":"upload"},"id":{"type":"string"},"status":{"type":"string","example":"aborted"}},"required":["object","id","status"]},"VersionDto":{"type":"object","properties":{"object":{"type":"string","example":"version"},"id":{"type":"string"},"file_id":{"type":"string"},"version_number":{"type":"number"},"size":{"type":"number"},"mime":{"type":"string"},"extension":{"type":"string"},"status":{"type":"string"},"duration_ms":{"type":"number","nullable":true},"resolution":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"string","nullable":true},"is_active":{"type":"boolean"}},"required":["object","id","file_id","version_number","size","mime","extension","status","duration_ms","resolution","created_at","created_by_id","is_active"]},"VersionListDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/VersionDto"}}},"required":["object","has_more","next_cursor","data"]},"AnnotationCoordinateDto":{"type":"object","properties":{"x":{"type":"number","description":"Normalized 0..1 against the media reference box."},"y":{"type":"number","description":"Normalized 0..1 against the media reference box."}},"required":["x","y"]},"AnnotationDto":{"type":"object","properties":{"type":{"type":"string","enum":["draw","arrow","rectangle","ellipse"]},"coordinates":{"description":"Normalized 0..1. arrow, rectangle and ellipse carry exactly 2 points (drag anchor and opposite corner); draw carries 2 to 2000. The reference box is the image content box for an image and a fixed 16:9 letterboxed player box for a video (comment-annotations.md).","type":"array","items":{"$ref":"#/components/schemas/AnnotationCoordinateDto"}}},"required":["type","coordinates"]},"CommentDto":{"type":"object","properties":{"object":{"type":"string","example":"comment"},"id":{"type":"string"},"file_id":{"type":"string"},"version_id":{"type":"string","nullable":true},"text":{"type":"string","description":"Mentions are inline `[@<user_id>]` tokens, as stored."},"author":{"nullable":true,"description":"null for an anonymous (shared-link visitor) comment.","type":"object","allOf":[{"$ref":"#/components/schemas/UserRefDto"}]},"anonymous_name":{"type":"string","nullable":true},"mentions":{"type":"array","items":{"$ref":"#/components/schemas/UserRefDto"}},"timestamp_ms":{"type":"number","nullable":true,"description":"Video / audio anchor."},"annotations":{"type":"array","items":{"$ref":"#/components/schemas/AnnotationDto"}},"resolved":{"type":"boolean"},"resolved_at":{"type":"string","format":"date-time","nullable":true},"resolved_by_id":{"type":"string","nullable":true},"has_replies":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"edited_at":{"type":"string","format":"date-time","nullable":true}},"required":["object","id","file_id","version_id","text","author","anonymous_name","mentions","timestamp_ms","annotations","resolved","resolved_at","resolved_by_id","has_replies","created_at","updated_at","edited_at"]},"CommentListDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/CommentDto"}}},"required":["object","has_more","next_cursor","data"]},"AnnotationCoordinateInputDto":{"type":"object","properties":{"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1}},"required":["x","y"]},"AnnotationInputDto":{"type":"object","properties":{"type":{"type":"string","enum":["draw","arrow","rectangle","ellipse"]},"coordinates":{"minItems":2,"maxItems":2000,"type":"array","items":{"$ref":"#/components/schemas/AnnotationCoordinateInputDto"}}},"required":["type","coordinates"]},"CreateCommentBodyDto":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1000,"description":"Mention a member with the inline token [@<user_id>]."},"timestamp_ms":{"type":"number","minimum":0,"description":"Video / audio anchor, in milliseconds."},"annotations":{"maxItems":50,"type":"array","items":{"$ref":"#/components/schemas/AnnotationInputDto"}},"version_id":{"type":"string","description":"A version of THIS file; anything else answers 404."}},"required":["text"]},"UpdateCommentBodyDto":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1000,"description":"The only editable field. Author only."}},"required":["text"]},"ReplyDto":{"type":"object","properties":{"object":{"type":"string","example":"reply"},"id":{"type":"string"},"comment_id":{"type":"string"},"text":{"type":"string"},"author":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/UserRefDto"}]},"anonymous_name":{"type":"string","nullable":true},"mentions":{"type":"array","items":{"$ref":"#/components/schemas/UserRefDto"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"edited_at":{"type":"string","format":"date-time","nullable":true}},"required":["object","id","comment_id","text","author","anonymous_name","mentions","created_at","updated_at","edited_at"]},"ReplyListDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/ReplyDto"}}},"required":["object","has_more","next_cursor","data"]},"CreateReplyBodyDto":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1000,"description":"Mention a member with the inline token [@<user_id>]."}},"required":["text"]},"UpdateReplyBodyDto":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":1000,"description":"The only editable field. Author only."}},"required":["text"]},"PageDto":{"type":"object","properties":{"object":{"type":"string","example":"page"},"id":{"type":"string","description":"The file id."},"name":{"type":"string"},"library_id":{"type":"string","nullable":true,"description":"null for a brandspace-root page."},"folder_id":{"type":"string","nullable":true},"published":{"type":"boolean"},"published_at":{"type":"string","format":"date-time","nullable":true},"published_by_id":{"type":"string","nullable":true},"public_url":{"type":"string","nullable":true,"description":"<web origin>/site/<id> while published, null otherwise."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","description":"The last save from any editor or API append."},"created_by_id":{"type":"string","nullable":true},"trashed_at":{"type":"string","format":"date-time","nullable":true}},"required":["object","id","name","library_id","folder_id","published","published_at","published_by_id","public_url","created_at","updated_at","created_by_id","trashed_at"]},"PageListDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/PageDto"}}},"required":["object","has_more","next_cursor","data"]},"BlockInputDto":{"type":"object","properties":{"type":{"type":"string","enum":["paragraph","heading","bullet_list","ordered_list","code_block","quote","divider"]},"text":{"type":"string","maxLength":20000,"description":"paragraph and quote cap at 10000, heading at 1000, code_block at 20000."},"level":{"type":"number","minimum":1,"maximum":3,"description":"heading only."},"items":{"minItems":1,"maxItems":500,"description":"bullet_list and ordered_list.","type":"array","items":{"type":"string"}},"language":{"type":"string","maxLength":40,"description":"code_block only."}},"required":["type"]},"CreatePageBodyDto":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256,"description":"No control or bidi-override characters."},"library_id":{"type":"string"},"folder_id":{"type":"string"},"to_root":{"type":"boolean","description":"The brandspace root (\"All files\")."},"blocks":{"maxItems":200,"description":"The initial content. An empty page when omitted.","type":"array","items":{"$ref":"#/components/schemas/BlockInputDto"}}},"required":["name"]},"PageContentDto":{"type":"object","properties":{"format":{"type":"string","enum":["json","markdown"]},"json":{"type":"object","nullable":true,"description":"The stored ProseMirror document, verbatim. null for a page that was never saved. Present only when format is json."},"markdown":{"type":"string","nullable":true,"description":"Server-side Markdown rendering of the stored snapshot. null for a page that was never saved. Present only when format is markdown."}},"required":["format"]},"PageDetailDto":{"type":"object","properties":{"object":{"type":"string","example":"page"},"id":{"type":"string","description":"The file id."},"name":{"type":"string"},"library_id":{"type":"string","nullable":true,"description":"null for a brandspace-root page."},"folder_id":{"type":"string","nullable":true},"published":{"type":"boolean"},"published_at":{"type":"string","format":"date-time","nullable":true},"published_by_id":{"type":"string","nullable":true},"public_url":{"type":"string","nullable":true,"description":"<web origin>/site/<id> while published, null otherwise."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","description":"The last save from any editor or API append."},"created_by_id":{"type":"string","nullable":true},"trashed_at":{"type":"string","format":"date-time","nullable":true},"content":{"$ref":"#/components/schemas/PageContentDto"}},"required":["object","id","name","library_id","folder_id","published","published_at","published_by_id","public_url","created_at","updated_at","created_by_id","trashed_at","content"]},"AppendBlocksBodyDto":{"type":"object","properties":{"blocks":{"minItems":1,"maxItems":200,"description":"Appended at the end of the document, in order.","type":"array","items":{"$ref":"#/components/schemas/BlockInputDto"}}},"required":["blocks"]},"SharedLinkTargetDto":{"type":"object","properties":{"type":{"type":"string","enum":["file","folder","library","board"]},"id":{"type":"string"}},"required":["type","id"]},"SharedLinkBoardViewsDto":{"type":"object","properties":{"default":{"type":"string","enum":["gallery","table"]},"allowed":{"type":"array","items":{"type":"string","enum":["gallery","table"]}}},"required":["default","allowed"]},"SharedLinkDto":{"type":"object","properties":{"object":{"type":"string","example":"shared_link"},"id":{"type":"string","description":"The 11-character short id, part of `url`."},"url":{"type":"string","description":"<web origin>/shared/<id>."},"target":{"$ref":"#/components/schemas/SharedLinkTargetDto"},"access":{"type":"string","enum":["view","download","review","upload"]},"password_protected":{"type":"boolean","description":"The password itself is never returned."},"expires_at":{"type":"string","format":"date-time","nullable":true},"expired":{"type":"boolean","description":"Computed at read time from expires_at."},"anonymous_comments":{"type":"boolean"},"show_versions":{"type":"boolean"},"show_properties":{"type":"boolean"},"display_mode":{"type":"string","enum":["grid","list","presentation"]},"board_views":{"nullable":true,"description":"board targets only, null otherwise.","type":"object","allOf":[{"$ref":"#/components/schemas/SharedLinkBoardViewsDto"}]},"view_count":{"type":"number"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"string"}},"required":["object","id","url","target","access","password_protected","expires_at","expired","anonymous_comments","show_versions","show_properties","display_mode","board_views","view_count","created_at","updated_at","created_by_id"]},"SharedLinkListDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/SharedLinkDto"}}},"required":["object","has_more","next_cursor","data"]},"SharedLinkTargetInputDto":{"type":"object","properties":{"type":{"type":"string","enum":["file","folder","library","board"]},"id":{"type":"string"}},"required":["type","id"]},"SharedLinkBoardViewsInputDto":{"type":"object","properties":{"default":{"type":"string","enum":["gallery","table"]},"allowed":{"type":"array","minItems":1,"items":{"type":"string","enum":["gallery","table"]}}},"required":["default","allowed"]},"CreateSharedLinkBodyDto":{"type":"object","properties":{"target":{"$ref":"#/components/schemas/SharedLinkTargetInputDto"},"access":{"type":"string","enum":["view","download","review","upload"],"default":"download"},"password":{"type":"string","minLength":4,"maxLength":72,"description":"Stored hashed; never returned. 4–72 BYTES — bcrypt ignores everything past 72."},"expires_at":{"type":"string","format":"date-time","description":"Must be in the future."},"anonymous_comments":{"type":"boolean","default":false,"description":"Visitors may comment without an account."},"board_views":{"description":"board targets only; required for one.","allOf":[{"$ref":"#/components/schemas/SharedLinkBoardViewsInputDto"}]}},"required":["target"]},"UpdateSharedLinkBodyDto":{"type":"object","properties":{"access":{"type":"string","enum":["view","download","review","upload"]},"password":{"type":"string","nullable":true,"minLength":4,"maxLength":72,"description":"null removes it. 4–72 BYTES when present."},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"null removes it."},"anonymous_comments":{"type":"boolean"},"show_versions":{"type":"boolean"},"show_properties":{"type":"boolean"},"display_mode":{"type":"string","enum":["grid","list","presentation"]},"board_views":{"description":"board targets only.","allOf":[{"$ref":"#/components/schemas/SharedLinkBoardViewsInputDto"}]}}},"TransferFileInputDto":{"type":"object","properties":{"id":{"type":"string"},"version_id":{"type":"string","description":"Send this exact version instead of the active one."}},"required":["id"]},"TransferUploadInputDto":{"type":"object","properties":{"name":{"type":"string","maxLength":256},"size":{"type":"number","minimum":1,"description":"Bytes. At least 1 — an empty object has nothing to upload."}},"required":["name","size"]},"CreateTransferBodyDto":{"type":"object","properties":{"files":{"maxItems":1000,"description":"Brault files to include.","type":"array","items":{"$ref":"#/components/schemas/TransferFileInputDto"}},"folders":{"maxItems":1000,"description":"Brault folder ids; the whole accessible subtree goes.","type":"array","items":{"type":"string"}},"uploads":{"maxItems":1000,"description":"Files you will upload for this transfer.","type":"array","items":{"$ref":"#/components/schemas/TransferUploadInputDto"}},"password":{"type":"string","maxLength":128,"description":"Stored hashed; never returned. Needs the plan’s transfer protection."},"expires_in_days":{"type":"number","minimum":1,"maximum":365,"default":7,"description":"Whole days from creation. Any value other than 7 needs the plan’s custom expiry."}}},"TransferUploadDto":{"type":"object","properties":{"object":{"type":"string","example":"transfer_upload"},"id":{"type":"string","description":"Address the upload sub-routes with this id."},"name":{"type":"string"},"size":{"type":"number","description":"Bytes, as declared."},"method":{"type":"string","enum":["put","multipart"],"description":"multipart above 256 MiB."},"url":{"type":"string","nullable":true,"description":"PUT the bytes here; null for multipart."},"part_size":{"type":"number","nullable":true,"description":"Bytes per part; multipart only."},"status":{"type":"string","enum":["pending","completed"]}},"required":["object","id","name","size","method","url","part_size","status"]},"TransferCreatedDto":{"type":"object","properties":{"object":{"type":"string","example":"transfer"},"id":{"type":"string","description":"The short /d/<id> slug; also the S3 prefix."},"url":{"type":"string","description":"https://<brandspace>.brault.app/d/<id>."},"status":{"type":"string","enum":["awaiting_uploads","processing","ready","expired"]},"size":{"type":"number","description":"Bytes of source content; an upper bound on the zip."},"file_count":{"type":"number"},"folder_count":{"type":"number"},"password_protected":{"type":"boolean","description":"The password itself is never returned."},"expires_at":{"type":"string","format":"date-time"},"view_count":{"type":"number"},"download_count":{"type":"number"},"zip_url":{"type":"string","nullable":true,"description":"A freshly signed zip URL, null until status is ready. Never cached."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"string"},"uploads":{"description":"One per declared upload; present only when the transfer opened as a draft.","type":"array","items":{"$ref":"#/components/schemas/TransferUploadDto"}}},"required":["object","id","url","status","size","file_count","folder_count","password_protected","expires_at","view_count","download_count","zip_url","created_at","updated_at","created_by_id"]},"TransferUploadStatusDto":{"type":"object","properties":{"object":{"type":"string","example":"transfer_upload"},"id":{"type":"string"},"status":{"type":"string","example":"completed"}},"required":["object","id","status"]},"TransferFileDto":{"type":"object","properties":{"name":{"type":"string"},"size":{"type":"number","description":"Bytes."},"mime":{"type":"string"},"path":{"type":"string","description":"Path inside the transfer, folders included."}},"required":["name","size","mime","path"]},"TransferFolderDto":{"type":"object","properties":{"name":{"type":"string"},"path":{"type":"string","description":"Path inside the transfer, ancestors first."}},"required":["name","path"]},"TransferDetailDto":{"type":"object","properties":{"object":{"type":"string","example":"transfer"},"id":{"type":"string","description":"The short /d/<id> slug; also the S3 prefix."},"url":{"type":"string","description":"https://<brandspace>.brault.app/d/<id>."},"status":{"type":"string","enum":["awaiting_uploads","processing","ready","expired"]},"size":{"type":"number","description":"Bytes of source content; an upper bound on the zip."},"file_count":{"type":"number"},"folder_count":{"type":"number"},"password_protected":{"type":"boolean","description":"The password itself is never returned."},"expires_at":{"type":"string","format":"date-time"},"view_count":{"type":"number"},"download_count":{"type":"number"},"zip_url":{"type":"string","nullable":true,"description":"A freshly signed zip URL, null until status is ready. Never cached."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"string"},"files":{"type":"array","items":{"$ref":"#/components/schemas/TransferFileDto"}},"folders":{"type":"array","items":{"$ref":"#/components/schemas/TransferFolderDto"}}},"required":["object","id","url","status","size","file_count","folder_count","password_protected","expires_at","view_count","download_count","zip_url","created_at","updated_at","created_by_id","files","folders"]},"TransferDto":{"type":"object","properties":{"object":{"type":"string","example":"transfer"},"id":{"type":"string","description":"The short /d/<id> slug; also the S3 prefix."},"url":{"type":"string","description":"https://<brandspace>.brault.app/d/<id>."},"status":{"type":"string","enum":["awaiting_uploads","processing","ready","expired"]},"size":{"type":"number","description":"Bytes of source content; an upper bound on the zip."},"file_count":{"type":"number"},"folder_count":{"type":"number"},"password_protected":{"type":"boolean","description":"The password itself is never returned."},"expires_at":{"type":"string","format":"date-time"},"view_count":{"type":"number"},"download_count":{"type":"number"},"zip_url":{"type":"string","nullable":true,"description":"A freshly signed zip URL, null until status is ready. Never cached."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"string"}},"required":["object","id","url","status","size","file_count","folder_count","password_protected","expires_at","view_count","download_count","zip_url","created_at","updated_at","created_by_id"]},"TransferListDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/TransferDto"}}},"required":["object","has_more","next_cursor","data"]},"UpdateTransferBodyDto":{"type":"object","properties":{"password":{"type":"string","nullable":true,"maxLength":128,"description":"null removes it. Setting one needs the plan’s transfer protection."},"expires_in_days":{"type":"number","minimum":1,"maximum":365,"description":"Whole days counted from TODAY, not from the transfer’s creation."}}},"BoardListDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/BoardDto"}}},"required":["object","has_more","next_cursor","data"]},"CreateBoardBodyDto":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256},"default_property_type":{"type":"string","enum":["status","person","date","checkbox","text","multi_tag"],"description":"Seeds one property of that type. `status` is seeded with the default options To Do, In Progress, Done. Omit for a board with no properties."}},"required":["name"]},"OptionDto":{"type":"object","properties":{"object":{"type":"string","example":"option"},"id":{"type":"string"},"label":{"type":"string"},"color":{"type":"string","example":"#E2E8EE"},"hidden":{"type":"boolean"},"position":{"type":"number","description":"0-based index within the property’s full options array, which is never paginated on its own."}},"required":["object","id","label","color","hidden","position"]},"PropertyDto":{"type":"object","properties":{"object":{"type":"string","example":"property"},"id":{"type":"string"},"scope":{"type":"string","enum":["board","brandspace"]},"board_id":{"type":"string","nullable":true,"description":"Set when `scope` is `board`."},"name":{"type":"string"},"type":{"type":"string","enum":["status","person","date","checkbox","text","multi_tag","tag","text","date","checkbox","person"],"description":"Board properties: status, person, date, checkbox, text, multi_tag. Brandspace properties: tag, text, date, checkbox, person."},"selection_mode":{"type":"string","nullable":true,"enum":["single","multiple"],"description":"Brandspace `tag` properties only."},"options":{"type":"array","items":{"$ref":"#/components/schemas/OptionDto"}},"position":{"type":"number","description":"0-based index over the whole sorted collection, not just this page — gapless overall, so page 2 starts at 50, not 0."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["object","id","scope","board_id","name","type","selection_mode","options","position","created_at","updated_at"]},"BoardDetailDto":{"type":"object","properties":{"object":{"type":"string","example":"board"},"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","example":"#E2E8EE"},"emoji":{"type":"string","nullable":true},"logo_url":{"type":"string","nullable":true,"description":"Public CDN URL of the uploaded logo; null when the board uses an emoji or nothing."},"pinned":{"type":"boolean"},"my_access":{"type":"string","enum":["view","edit","manage"],"description":"The key creator’s own level on this board."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"string","nullable":true},"properties":{"description":"The board’s properties, in position order.","type":"array","items":{"$ref":"#/components/schemas/PropertyDto"}}},"required":["object","id","name","color","emoji","logo_url","pinned","my_access","created_at","updated_at","created_by_id","properties"]},"UpdateBoardBodyDto":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256},"color":{"type":"string","example":"#E2E8EE"},"emoji":{"type":"string","maxLength":50,"description":"The empty string clears it."},"pinned":{"type":"boolean","description":"Applied after the other fields."}}},"BoardMemberDto":{"type":"object","properties":{"object":{"type":"string","example":"board_member"},"user_id":{"type":"string","description":"Resolve to a name or email with GET /v1/members/{userId} (members:read)."}},"required":["object","user_id"]},"BoardMemberListDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/BoardMemberDto"}}},"required":["object","has_more","next_cursor","data"]},"PropertyListDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/PropertyDto"}}},"required":["object","has_more","next_cursor","data"]},"CreateStatusOptionInputDto":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":100},"color":{"type":"string","example":"#E2E8EE"}},"required":["label"]},"CreateBoardPropertyBodyDto":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256},"type":{"type":"string","enum":["status","person","date","checkbox","text","multi_tag"]},"options":{"description":"`status` properties only. A `multi_tag` property is created with one default option.","type":"array","items":{"$ref":"#/components/schemas/CreateStatusOptionInputDto"}}},"required":["name","type"]},"UpdateBoardPropertyBodyDto":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256,"description":"The only editable field — a property’s type is fixed."}},"required":["name"]},"CreateOptionBodyDto":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":100},"color":{"type":"string","example":"#E2E8EE"}},"required":["label"]},"UpdateOptionBodyDto":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":100},"color":{"type":"string","example":"#E2E8EE"},"hidden":{"type":"boolean","description":"A hidden option stays a valid value; the webapp folds it away."}}},"QueryBoardFilesBodyDto":{"type":"object","properties":{"filter":{"type":"object","additionalProperties":true,"description":"A filter document (boards.md § 5): { \"and\": [ … ] }, { \"or\": [ … ] } or a single condition. Conditions only — no nested groups. Absent means every file on the board."},"q":{"type":"string","maxLength":500,"description":"Keyword search over the board’s files (name and tags). Plain keyword — no natural-language interpretation on boards. Consumes the search rate bucket."},"sort":{"type":"string","enum":["manual","added_at","gallery","table"],"default":"manual","description":"`manual` is the board’s own order; `gallery` and `table` are the manual orders of the webapp’s Gallery and Table views and are always ascending."},"order":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Applies to `manual` and `added_at`."},"limit":{"type":"number","minimum":1,"maximum":100,"default":50},"cursor":{"type":"string","description":"Opaque cursor from a previous response."}}},"BoardFileDto":{"type":"object","properties":{"object":{"type":"string","example":"board_file"},"board_id":{"type":"string"},"file":{"$ref":"#/components/schemas/FileDto"},"values":{"description":"This board’s values for the file; only properties that have a value appear.","type":"array","items":{"$ref":"#/components/schemas/PropertyValueDto"}},"added_at":{"type":"string","format":"date-time"}},"required":["object","board_id","file","values","added_at"]},"BoardFileListDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/BoardFileDto"}}},"required":["object","has_more","next_cursor","data"]},"AddBoardFilesBodyDto":{"type":"object","properties":{"file_ids":{"minItems":1,"maxItems":100,"description":"No duplicates.","type":"array","items":{"type":"string"}}},"required":["file_ids"]},"BoardFileBatchResultDto":{"type":"object","properties":{"file_id":{"type":"string"},"status":{"type":"string","enum":["added","already_in_board"]}},"required":["file_id","status"]},"BoardFilesBatchDto":{"type":"object","properties":{"object":{"type":"string","example":"board_files_batch"},"board_id":{"type":"string"},"results":{"description":"One entry per id sent, in the order sent.","type":"array","items":{"$ref":"#/components/schemas/BoardFileBatchResultDto"}}},"required":["object","board_id","results"]},"StatusValueInputDto":{"type":"object","properties":{"option_id":{"type":"string","description":"An option of this property."}},"required":["option_id"]},"SetBoardValueBodyDto":{"type":"object","properties":{"status":{"nullable":true,"description":"`null` clears the value.","type":"object","allOf":[{"$ref":"#/components/schemas/StatusValueInputDto"}]},"person":{"nullable":true,"description":"`null` clears the value.","type":"object","allOf":[{"$ref":"#/components/schemas/PersonValueInputDto"}]},"date":{"nullable":true,"description":"`null` clears the value.","type":"object","allOf":[{"$ref":"#/components/schemas/DateValueInputDto"}]},"checkbox":{"type":"boolean","nullable":true,"description":"`null` clears the value."},"text":{"type":"string","nullable":true,"maxLength":600,"description":"`null` clears the value."},"multi_tag":{"description":"Add and/or remove options. There is no null form for a tag list — remove them all instead.","allOf":[{"$ref":"#/components/schemas/TagWriteDto"}]}}},"CreateBrandspacePropertyBodyDto":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256},"type":{"type":"string","enum":["tag","text","date","checkbox","person"]},"selection_mode":{"type":"string","enum":["single","multiple"],"description":"`tag` properties only; defaults to `multiple`."}},"required":["name","type"]},"UpdateBrandspacePropertyBodyDto":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":256},"selection_mode":{"type":"string","enum":["single","multiple"],"description":"`tag` properties only."}}},"CreateBrandspaceOptionBodyDto":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":256},"color":{"type":"string","example":"#E2E8EE"}},"required":["label"]},"UpdateBrandspaceOptionBodyDto":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":256},"color":{"type":"string","example":"#E2E8EE"},"hidden":{"type":"boolean","description":"A hidden option stays a valid value; the webapp folds it away."}}},"NaturalLanguageDto":{"type":"object","properties":{"parsed_query":{"type":"object","description":"How the query was interpreted, as the search engine parsed it."},"scope_intent":{"type":"string","example":"current"}},"required":["parsed_query","scope_intent"]},"SearchResultsDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"description":"Files and folders, distinguished by their `object` field.","type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/FileDto"},{"$ref":"#/components/schemas/FolderDto"}]}},"natural_language":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/NaturalLanguageDto"}]}},"required":["object","has_more","next_cursor","data","natural_language"]},"RoleRefDto":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string","example":"admin"}},"required":["id","name","slug"]},"MemberDto":{"type":"object","properties":{"object":{"type":"string","example":"member"},"id":{"type":"string","description":"The user id, the same id `created_by_id` and `uploaded_by` use."},"name":{"type":"string","nullable":true},"email":{"type":"string","description":"Requires the members:read scope."},"avatar_url":{"type":"string","nullable":true},"role":{"$ref":"#/components/schemas/RoleRefDto"},"joined_at":{"type":"string","format":"date-time"}},"required":["object","id","name","email","avatar_url","role","joined_at"]},"MemberListDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/MemberDto"}}},"required":["object","has_more","next_cursor","data"]},"RoleDto":{"type":"object","properties":{"object":{"type":"string","example":"role"},"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"is_default":{"type":"boolean"},"permissions":{"description":"Permission keys granted by this role.","type":"array","items":{"type":"string"}}},"required":["object","id","name","slug","description","is_default","permissions"]},"RoleListDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/RoleDto"}}},"required":["object","has_more","next_cursor","data"]},"BrandspaceDto":{"type":"object","properties":{"object":{"type":"string","example":"brandspace"},"id":{"type":"string"},"name":{"type":"string"},"username":{"type":"string","description":"Subdomain of the brandspace."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","name","username","created_at"]},"WebhookDto":{"type":"object","properties":{"object":{"type":"string","example":"webhook"},"id":{"type":"string"},"url":{"type":"string","description":"https only, port 443 or 8443, no credentials."},"name":{"type":"string","nullable":true,"maxLength":60},"events":{"description":"Catalogue tokens, or the single element \"*\".","type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","paused","disabled"]},"disabled_reason":{"type":"string","nullable":true,"description":"consecutive_failures or no_success_24h; null unless status is disabled."},"secret":{"type":"string","nullable":true,"description":"The signing secret, returned ONLY by POST /v1/webhooks and POST /v1/webhooks/{webhookId}/roll-secret. Null everywhere else; it is never stored in plaintext and cannot be read back."},"secret_last4":{"type":"string","description":"Last 4 characters of the current secret, for display."},"secret_rolled_at":{"type":"string","format":"date-time","nullable":true},"consecutive_failures":{"type":"number","description":"Exhausted deliveries since the last success."},"last_delivery_at":{"type":"string","format":"date-time","nullable":true},"last_success_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by_id":{"type":"string"}},"required":["object","id","url","name","events","status","disabled_reason","secret","secret_last4","secret_rolled_at","consecutive_failures","last_delivery_at","last_success_at","created_at","updated_at","created_by_id"]},"WebhookListDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDto"}}},"required":["object","has_more","next_cursor","data"]},"CreateWebhookBodyDto":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"example":"https://example.com/hooks/brault"},"name":{"type":"string","maxLength":60,"description":"Empty or whitespace-only is stored as null."},"events":{"minItems":1,"maxItems":58,"description":"Catalogue tokens from GET /v1/events, or the single element \"*\".","type":"array","items":{"type":"string"}}},"required":["url","events"]},"UpdateWebhookBodyDto":{"type":"object","properties":{"url":{"type":"string","maxLength":2048},"name":{"type":"string","nullable":true,"maxLength":60,"description":"null clears it."},"events":{"maxItems":58,"description":"Replaces the list.","type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["active","paused"],"description":"disabled is set by the system only."}}},"DeliveryDto":{"type":"object","properties":{"object":{"type":"string","example":"delivery"},"id":{"type":"string","description":"The value in Brault-Delivery-Id."},"webhook_id":{"type":"string"},"event_id":{"type":"string","description":"The evt_-shaped id in the payload and in Brault-Event-Id."},"event_type":{"type":"string"},"status":{"type":"string","enum":["pending","success","failed","exhausted","parked"],"description":"failed = this attempt failed and another is scheduled; exhausted = no attempt left; parked = the endpoint is disabled and the row waits for it to be re-enabled."},"attempt":{"type":"number","minimum":1,"maximum":8},"scheduled_at":{"type":"string","format":"date-time"},"delivered_at":{"type":"string","format":"date-time","nullable":true},"http_status":{"type":"number","nullable":true,"description":"Null when the request got no response."},"duration_ms":{"type":"number","nullable":true},"error_code":{"type":"string","nullable":true,"description":"timeout, dns_failure, tls_failure, connection_refused, redirect_refused, destination_private, http_error, unknown, endpoint_deleted, endpoint_disabled, signing_unavailable, parked_expired. A documented extensible enum: treat an unknown value as a failure."},"response_excerpt":{"type":"string","nullable":true,"description":"First 1 KB of the response body."},"request_id":{"type":"string","description":"The X-Request-Id the dispatcher sent."},"origin":{"type":"string","enum":["fanout","replay","redeliver","resume","test"],"description":"Why this row exists: ordinary fan-out, a window replay, a per-delivery redelivery, a parked row released by a re-enable, or POST /test. Rows written before v1.3.0 read \"fanout\"."},"replayed_from_id":{"type":"string","nullable":true,"description":"The terminal delivery a redeliver copied; null on every other origin."},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","webhook_id","event_id","event_type","status","attempt","scheduled_at","delivered_at","http_status","duration_ms","error_code","response_excerpt","request_id","origin","replayed_from_id","created_at"]},"DeliveryListDto":{"type":"object","properties":{"object":{"type":"string","example":"list"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryDto"}}},"required":["object","has_more","next_cursor","data"]},"ReplayBodyDto":{"type":"object","properties":{"from":{"type":"string","format":"date-time","description":"Inclusive start of the window."},"to":{"type":"string","format":"date-time","description":"Exclusive end of the window. At most 7 days after `from`."},"event_types":{"minItems":1,"maxItems":58,"description":"Catalogue tokens from GET /v1/events. Narrows the replay; the endpoint’s own `events` still apply, so this can only shrink the match. \"*\" is not accepted here.","type":"array","items":{"type":"string"}},"include_delivered":{"type":"boolean","description":"Default false. When true, an event this endpoint already delivered successfully is replayed too."}},"required":["from","to"]},"ReplayDto":{"type":"object","properties":{"object":{"type":"string","example":"replay"},"webhook_id":{"type":"string","description":"The endpoint the deliveries were created for."},"from":{"type":"string","format":"date-time","description":"The window’s inclusive start, echoed."},"to":{"type":"string","format":"date-time","description":"The window’s exclusive end, echoed."},"events_matched":{"type":"number","description":"Outbox rows in [from, to) whose type the endpoint subscribes to now."},"deliveries_created":{"type":"number","description":"Pending deliveries written, each with origin \"replay\"."},"skipped_delivered":{"type":"number","description":"Matched events skipped as already delivered. Always 0 when include_delivered is true."}},"required":["object","webhook_id","from","to","events_matched","deliveries_created","skipped_delivered"]}}}}