{"openapi":"3.1.0","info":{"title":"Mjhr API","version":"1.0.0","description":"Workspace API for reading Mjhr reference IDs, searches, search results, folders, Branch Lists, and workspace metadata."},"servers":[{"url":"https://api.mjhr.ai/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Workspace"},{"name":"Reference"},{"name":"Searches"},{"name":"Results"},{"name":"Folders"},{"name":"Lists"}],"paths":{"/workspace":{"get":{"operationId":"get_workspace","tags":["Workspace"],"summary":"Get workspace metadata","description":"Requires the `workspaceRead` scope.","responses":{"200":{"description":"Workspace metadata and plan usage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceResponse"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/countries":{"get":{"operationId":"list_countries","tags":["Reference"],"summary":"List Search country references","description":"Requires the `referenceRead` scope. Returns country codes and labels that can be used in `POST /v1/searches` countryCodes.","parameters":[{"name":"q","in":"query","required":false,"description":"Country code or label text.","schema":{"type":"string"}},{"name":"skip","in":"query","required":false,"description":"Number of rows to skip. Defaults to 0.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","required":false,"description":"Maximum number of rows to return. Defaults to 50, maximum 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Country references usable in Search creation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountryReferenceListResponse"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cities":{"get":{"operationId":"list_cities","tags":["Reference"],"summary":"List Search city references","description":"Requires the `referenceRead` scope. Returns city IDs and labels that can be used in `POST /v1/searches` cityIds.","parameters":[{"name":"q","in":"query","required":false,"description":"City slug or label text.","schema":{"type":"string"}},{"name":"countryCode","in":"query","required":false,"description":"Country code filter, for example `SA`.","schema":{"type":"string"}},{"name":"skip","in":"query","required":false,"description":"Number of rows to skip. Defaults to 0.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","required":false,"description":"Maximum number of rows to return. Defaults to 50, maximum 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"City references usable in Search creation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CityReferenceListResponse"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cities/{cityId}":{"get":{"operationId":"get_city","tags":["Reference"],"summary":"Get a Search city reference","description":"Requires the `referenceRead` scope. Returns one public city reference.","parameters":[{"name":"cityId","in":"path","required":true,"description":"Public city ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"A single city reference.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CityReferenceResponse"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cities/{cityId}/districts":{"get":{"operationId":"list_city_districts","tags":["Reference"],"summary":"List city district references","description":"Requires the `referenceRead` scope. Returns district IDs, labels, and coordinates for city reference workflows.","parameters":[{"name":"cityId","in":"path","required":true,"description":"Public city ID.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"District slug or label text.","schema":{"type":"string"}},{"name":"skip","in":"query","required":false,"description":"Number of rows to skip. Defaults to 0.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","required":false,"description":"Maximum number of rows to return. Defaults to 50, maximum 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"District references for one city.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DistrictReferenceListResponse"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/categories":{"get":{"operationId":"list_categories","tags":["Reference"],"summary":"List Search category references","description":"Requires the `referenceRead` scope. Returns category IDs and labels that can be used in `POST /v1/searches` categoryIds.","parameters":[{"name":"q","in":"query","required":false,"description":"Category slug or label text.","schema":{"type":"string"}},{"name":"skip","in":"query","required":false,"description":"Number of rows to skip. Defaults to 0.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","required":false,"description":"Maximum number of rows to return. Defaults to 50, maximum 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Category references usable in Search creation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryReferenceListResponse"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/searches":{"get":{"operationId":"list_searches","tags":["Searches"],"summary":"List saved searches","description":"Requires the `searchesRead` scope.","parameters":[{"name":"q","in":"query","required":false,"description":"Search title or prompt text.","schema":{"type":"string"}},{"name":"folderId","in":"query","required":false,"description":"Public folder ID or `unfiled`.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of rows to return. Defaults to 50, maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Saved searches visible to the API key workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchListResponse"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create_search","tags":["Searches"],"summary":"Submit a new saved search","description":"Requires the `searchesWrite` scope. Creates a workspace saved search using the same plan gates as the dashboard composer.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSearchRequest"}}}},"responses":{"201":{"description":"Created saved search.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSearchResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/searches/{searchId}":{"get":{"operationId":"get_search","tags":["Searches"],"summary":"Get a saved search","description":"Requires the `searchesRead` scope.","parameters":[{"name":"searchId","in":"path","required":true,"description":"Public search ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"A single saved search.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/searches/{searchId}/results":{"get":{"operationId":"list_search_results","tags":["Results"],"summary":"List saved search results","description":"Requires the `resultsRead` scope.","parameters":[{"name":"searchId","in":"path","required":true,"description":"Public search ID.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of rows to return. Defaults to 50, maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Companies and branches saved under the search.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResultListResponse"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/results/{searchId}":{"get":{"operationId":"list_result_companies","tags":["Results"],"summary":"List result companies","description":"Requires the `resultsRead` scope. Returns one company row per company saved under the result set.","parameters":[{"name":"searchId","in":"path","required":true,"description":"Public search ID.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of rows to return. Defaults to 50, maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Companies saved under the result set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultCompanyListResponse"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/results/{searchId}/branches":{"get":{"operationId":"list_result_branches","tags":["Results"],"summary":"List result branches","description":"Requires the `resultsRead` scope. Returns every branch for the companies saved under the result set.","parameters":[{"name":"searchId","in":"path","required":true,"description":"Public search ID.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of rows to return. Defaults to 50, maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Branches saved under the result set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultBranchListResponse"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/results/{searchId}/{companyId}":{"get":{"operationId":"list_company_result_branches","tags":["Results"],"summary":"List one result company’s branches","description":"Requires the `resultsRead` scope. Returns branches for one company within the result set.","parameters":[{"name":"searchId","in":"path","required":true,"description":"Public search ID.","schema":{"type":"string"}},{"name":"companyId","in":"path","required":true,"description":"Public company ID.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of rows to return. Defaults to 50, maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Branches for one company in the result set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultBranchListResponse"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/results/{searchId}/folder":{"post":{"operationId":"move_result_to_folder","tags":["Results"],"summary":"Move a result set to a folder","description":"Requires the `resultsWrite` scope. Moves the saved result set to a folder, or removes it from folders when `folderId` is null.","parameters":[{"name":"searchId","in":"path","required":true,"description":"Public search ID.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveResultToFolderRequest"}}}},"responses":{"200":{"description":"Updated result set folder placement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResultMoveResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/results/{searchId}/archive":{"post":{"operationId":"archive_result_set","tags":["Results"],"summary":"Archive a result set","description":"Requires the `resultsWrite` scope. Archives the saved search and its result set from workspace history.","parameters":[{"name":"searchId","in":"path","required":true,"description":"Public search ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"Archived result set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveResultResponse"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/folders":{"get":{"operationId":"list_folders","tags":["Folders"],"summary":"List search-history folders","description":"Requires the `foldersRead` scope.","parameters":[{"name":"limit","in":"query","required":false,"description":"Maximum number of rows to return. Defaults to 50, maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Workspace search-history folders.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderListResponse"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create_folder","tags":["Folders"],"summary":"Create a search-history folder","description":"Requires the `foldersWrite` scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFolderRequest"}}}},"responses":{"201":{"description":"Created folder.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FolderResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with existing state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/folders/{folderId}/archive":{"post":{"operationId":"archive_folder","tags":["Folders"],"summary":"Archive a search-history folder","description":"Requires the `foldersWrite` scope. Archives the folder and the saved searches inside it.","parameters":[{"name":"folderId","in":"path","required":true,"description":"Public folder ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"Archived folder.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveFolderResponse"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lists":{"get":{"operationId":"list_branch_lists","tags":["Lists"],"summary":"List active Branch Lists","description":"Requires the `listsRead` scope. Returns active Lists in the API key Workspace.","parameters":[{"name":"q","in":"query","required":false,"description":"List name text.","schema":{"type":"string"}},{"name":"skip","in":"query","required":false,"description":"Number of rows to skip. Defaults to 0.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","required":false,"description":"Maximum number of rows to return. Defaults to 50, maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Active Workspace Branch Lists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BranchListListResponse"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"create_branch_list","tags":["Lists"],"summary":"Create a Branch List","description":"Requires the `listsWrite` scope. Creates an empty List in the API key Workspace.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BranchListNameRequest"}}}},"responses":{"201":{"description":"Created Branch List.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BranchListResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lists/{listId}":{"get":{"operationId":"get_branch_list","tags":["Lists"],"summary":"Get Branch List metadata","description":"Requires the `listsRead` scope. Returns one active List in the API key Workspace.","parameters":[{"name":"listId","in":"path","required":true,"description":"Public Branch List ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"Active Branch List metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BranchListResponse"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lists/{listId}/rename":{"post":{"operationId":"rename_branch_list","tags":["Lists"],"summary":"Rename a Branch List","description":"Requires the `listsWrite` scope. Renames one active List in the API key Workspace.","parameters":[{"name":"listId","in":"path","required":true,"description":"Public Branch List ID.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BranchListNameRequest"}}}},"responses":{"200":{"description":"Renamed Branch List.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BranchListResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lists/{listId}/archive":{"post":{"operationId":"archive_branch_list","tags":["Lists"],"summary":"Archive a Branch List","description":"Requires the `listsWrite` scope. Archives the List without archiving Branches or Saved Searches.","parameters":[{"name":"listId","in":"path","required":true,"description":"Public Branch List ID.","schema":{"type":"string"}}],"responses":{"200":{"description":"Archived Branch List.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveBranchListResponse"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lists/{listId}/members":{"get":{"operationId":"list_branch_list_members","tags":["Lists"],"summary":"List Branch List members","description":"Requires the `listsRead` scope. Returns current canonical Branch data in stable List order.","parameters":[{"name":"listId","in":"path","required":true,"description":"Public Branch List ID.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Branch, Company, address, category, city, or district text.","schema":{"type":"string"}},{"name":"availability","in":"query","required":false,"description":"`available` or `unavailable`.","schema":{"type":"string"}},{"name":"companyId","in":"query","required":false,"description":"Public Company ID.","schema":{"type":"string"}},{"name":"category","in":"query","required":false,"description":"Category label text.","schema":{"type":"string"}},{"name":"countryCode","in":"query","required":false,"description":"Country code.","schema":{"type":"string"}},{"name":"city","in":"query","required":false,"description":"City label text.","schema":{"type":"string"}},{"name":"skip","in":"query","required":false,"description":"Number of rows to skip. Defaults to 0.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","required":false,"description":"Maximum number of rows to return. Defaults to 50, maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Current canonical Branch List membership in stable manual order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BranchListMemberListResponse"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"add_branch_list_members","tags":["Lists"],"summary":"Add Branches to a List","description":"Requires the `listsWrite` scope. Adds Branches visible in the supplied source Saved Search; duplicates are no-ops.","parameters":[{"name":"listId","in":"path","required":true,"description":"Public Branch List ID.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddBranchListMembersRequest"}}}},"responses":{"200":{"description":"Branch List addition counts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddBranchListMembersResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lists/{listId}/members/remove":{"post":{"operationId":"remove_branch_list_members","tags":["Lists"],"summary":"Remove Branches from a List","description":"Requires the `listsWrite` scope. Atomically removes only the selected List memberships.","parameters":[{"name":"listId","in":"path","required":true,"description":"Public Branch List ID.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BranchIdsRequest"}}}},"responses":{"200":{"description":"Removed membership count.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveBranchListMembersResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lists/{listId}/order":{"post":{"operationId":"reorder_branch_list_members","tags":["Lists"],"summary":"Replace Branch List order","description":"Requires the `listsWrite` scope. Atomically replaces the complete List order; partial orders are rejected.","parameters":[{"name":"listId","in":"path","required":true,"description":"Public Branch List ID.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BranchIdsRequest"}}}},"responses":{"200":{"description":"Reordered membership count.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReorderBranchListMembersResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected API failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Mjhr API key generated in Dashboard > Integrations > API Keys."}},"schemas":{"LocalizedText":{"type":"object","additionalProperties":false,"properties":{"en":{"type":"string"},"ar":{"type":"string"}},"required":["en","ar"]},"NullableLocalizedText":{"type":"object","additionalProperties":false,"properties":{"en":{"type":["string","null"]},"ar":{"type":["string","null"]}},"required":["en","ar"]},"Workspace":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public workspace ID."},"name":{"type":"string","description":"Workspace display name."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","createdAt","updatedAt"]},"WorkspacePlan":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","description":"Plan key."},"name":{"type":"string","description":"Plan display name."},"companyAllowance":{"type":"integer","description":"Company records included in the plan cycle."},"perSearchCompanyCap":{"type":"integer","description":"Maximum saved companies per search."},"participantLimit":{"type":"integer","description":"Maximum workspace participants."},"custom":{"type":"boolean","description":"True when the workspace has an override."}},"required":["kind","name","companyAllowance","perSearchCompanyCap","participantLimit","custom"]},"WorkspaceUsage":{"type":"object","additionalProperties":false,"properties":{"savedSearches":{"type":"integer","description":"Current saved search count."},"savedCompanies":{"type":"integer","description":"Current saved company count across searches."},"folders":{"type":"integer","description":"Current folder count."},"lists":{"type":"integer","description":"Current active Branch List count."}},"required":["savedSearches","savedCompanies","folders","lists"]},"WorkspaceResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"workspace":{"$ref":"#/components/schemas/Workspace"},"plan":{"$ref":"#/components/schemas/WorkspacePlan"},"usage":{"$ref":"#/components/schemas/WorkspaceUsage"}},"required":["ok","workspace","plan","usage"]},"ReferencePagination":{"type":"object","additionalProperties":false,"properties":{"skip":{"type":"integer","description":"Number of rows skipped."},"limit":{"type":"integer","description":"Maximum rows requested."},"returned":{"type":"integer","description":"Rows returned in this response."},"total":{"type":"integer","description":"Total matching rows."},"hasMore":{"type":"boolean","description":"True when another page is available."},"nextSkip":{"type":["integer","null"],"description":"Skip value for the next page, or null."}},"required":["skip","limit","returned","total","hasMore","nextSkip"]},"CountryReference":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Country code to pass as a `countryCodes` entry."},"label":{"type":"string","description":"English display label."},"labelAr":{"type":["string","null"],"description":"Arabic display label, when available."}},"required":["code","label","labelAr"]},"CountryReferenceListResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"countries":{"type":"array","items":{"$ref":"#/components/schemas/CountryReference"}},"pagination":{"$ref":"#/components/schemas/ReferencePagination"}},"required":["ok","countries","pagination"]},"CityReference":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public city ID to pass as a `cityIds` entry."},"slug":{"type":"string","description":"City slug."},"label":{"type":"string","description":"English display label."},"labelAr":{"type":["string","null"],"description":"Arabic display label, when available."},"countryCode":{"type":"string","description":"Country code for this city."}},"required":["id","slug","label","labelAr","countryCode"]},"CityReferenceListResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"cities":{"type":"array","items":{"$ref":"#/components/schemas/CityReference"}},"pagination":{"$ref":"#/components/schemas/ReferencePagination"}},"required":["ok","cities","pagination"]},"CityReferenceResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"city":{"$ref":"#/components/schemas/CityReference"}},"required":["ok","city"]},"DistrictReference":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public district ID for reference workflows."},"slug":{"type":"string","description":"District slug."},"label":{"type":"string","description":"English display label."},"labelAr":{"type":["string","null"],"description":"Arabic display label, when available."},"cityId":{"type":"string","description":"Public city ID that owns this district."},"lat":{"type":"number","description":"District latitude."},"lng":{"type":"number","description":"District longitude."}},"required":["id","slug","label","labelAr","cityId","lat","lng"]},"DistrictReferenceListResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"districts":{"type":"array","items":{"$ref":"#/components/schemas/DistrictReference"}},"pagination":{"$ref":"#/components/schemas/ReferencePagination"}},"required":["ok","districts","pagination"]},"CategoryReference":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public category ID to pass as a `categoryIds` entry."},"slug":{"type":"string","description":"Category slug."},"label":{"type":"string","description":"English display label."},"labelAr":{"type":["string","null"],"description":"Arabic display label, when available."}},"required":["id","slug","label","labelAr"]},"CategoryReferenceListResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"categories":{"type":"array","items":{"$ref":"#/components/schemas/CategoryReference"}},"pagination":{"$ref":"#/components/schemas/ReferencePagination"}},"required":["ok","categories","pagination"]},"SearchFilters":{"type":"object","additionalProperties":false,"properties":{"companyTypes":{"type":"array","items":{"type":"string"},"description":"Company type filters used by the saved search."},"categoryIds":{"type":"array","items":{"type":"string"},"description":"Public category IDs used by the saved search."},"countryCodes":{"type":"array","items":{"type":"string"},"description":"Country codes used by the saved search."},"cityIds":{"type":"array","items":{"type":"string"},"description":"Public city IDs used by the saved search."},"location":{"anyOf":[{"$ref":"#/components/schemas/SearchLocationFilter"},{"type":"null"}],"description":"Coordinate radius filter used by the saved search, or null."}},"required":["companyTypes","categoryIds","countryCodes","cityIds","location"]},"SearchLocationFilter":{"type":"object","additionalProperties":false,"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in decimal degrees."},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in decimal degrees."},"radiusKm":{"type":"number","exclusiveMinimum":0,"maximum":25,"description":"Radius around the coordinate in kilometers."}},"required":["lat","lng","radiusKm"]},"Search":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public search ID."},"folderId":{"type":["string","null"],"description":"Public folder ID, or null when unfiled."},"title":{"type":"string","description":"Saved search title."},"prompt":{"type":"string","description":"Prompt used to create the saved search."},"filters":{"$ref":"#/components/schemas/SearchFilters"},"requestedResultCount":{"type":"integer","description":"Requested result count."},"persistedResultCount":{"type":"integer","description":"Saved result count."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","folderId","title","prompt","filters","requestedResultCount","persistedResultCount","createdAt","updatedAt"]},"SearchListResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"searches":{"type":"array","items":{"$ref":"#/components/schemas/Search"}}},"required":["ok","searches"]},"SearchResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"search":{"$ref":"#/components/schemas/Search"}},"required":["ok","search"]},"CreateSearchRequest":{"type":"object","additionalProperties":false,"properties":{"prompt":{"type":"string","description":"Search prompt. Required when no filter arrays are provided."},"companyTypes":{"type":"array","items":{"type":"string"},"description":"Optional company type filters."},"categoryIds":{"type":"array","items":{"type":"string"},"description":"Optional public category IDs."},"countryCodes":{"type":"array","items":{"type":"string"},"description":"Optional country codes."},"cityIds":{"type":"array","items":{"type":"string"},"description":"Optional public city IDs."},"location":{"$ref":"#/components/schemas/SearchLocationFilter","description":"Optional coordinate radius filter. Matches existing indexed branches only."},"requestedResultCount":{"type":"integer","minimum":1,"default":10,"description":"Requested number of companies to save."},"folderId":{"type":["string","null"],"description":"Optional public folder ID, or null for unfiled."}},"required":[]},"CreateSearchResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"search":{"$ref":"#/components/schemas/Search"},"resultCount":{"type":"integer","description":"Number of saved result branches."},"message":{"type":["string","null"],"description":"Plan-gate message when fewer records were saved."}},"required":["ok","search","resultCount","message"]},"SearchResultCompany":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public company ID."},"name":{"$ref":"#/components/schemas/NullableLocalizedText"},"legalName":{"$ref":"#/components/schemas/NullableLocalizedText"},"website":{"type":["string","null"],"description":"Company website URL."},"websiteDomain":{"type":["string","null"],"description":"Company website domain."},"phone":{"type":["string","null"],"description":"Company phone number."}},"required":["id","name","legalName","website","websiteDomain","phone"]},"SearchResultBranch":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public branch ID."},"name":{"$ref":"#/components/schemas/NullableLocalizedText"},"address":{"$ref":"#/components/schemas/NullableLocalizedText"},"website":{"type":["string","null"],"description":"Branch website URL."},"phone":{"type":["string","null"],"description":"Branch phone number."},"lat":{"type":["number","null"],"description":"Branch latitude."},"lng":{"type":["number","null"],"description":"Branch longitude."},"rating":{"type":["number","null"],"description":"Branch public rating."},"reviews":{"type":["integer","null"],"description":"Branch public review count."}},"required":["id","name","address","website","phone","lat","lng","rating","reviews"]},"LocationPart":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public location ID."},"name":{"$ref":"#/components/schemas/LocalizedText"}},"required":["id","name"]},"CountryLocationPart":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public country ID."},"code":{"type":"string","description":"ISO-like country code."},"name":{"$ref":"#/components/schemas/LocalizedText"}},"required":["id","code","name"]},"SearchResultLocation":{"type":"object","additionalProperties":false,"properties":{"district":{"$ref":"#/components/schemas/LocationPart"},"city":{"$ref":"#/components/schemas/LocationPart"},"region":{"$ref":"#/components/schemas/LocationPart"},"country":{"$ref":"#/components/schemas/CountryLocationPart"}},"required":["district","city","region","country"]},"SearchResult":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public search result ID."},"createdAt":{"type":"string","format":"date-time"},"company":{"$ref":"#/components/schemas/SearchResultCompany"},"branch":{"$ref":"#/components/schemas/SearchResultBranch"},"location":{"$ref":"#/components/schemas/SearchResultLocation"}},"required":["id","createdAt","company","branch","location"]},"SearchResultListResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}}},"required":["ok","results"]},"ResultCompany":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public company ID."},"name":{"$ref":"#/components/schemas/NullableLocalizedText"},"legalName":{"$ref":"#/components/schemas/NullableLocalizedText"},"website":{"type":["string","null"],"description":"Company website URL."},"websiteDomain":{"type":["string","null"],"description":"Company website domain."},"phone":{"type":["string","null"],"description":"Company phone number."},"branchCount":{"type":"integer","description":"Number of saved branches for this company."},"firstSavedAt":{"type":"string","format":"date-time"},"lastSavedAt":{"type":"string","format":"date-time"}},"required":["id","name","legalName","website","websiteDomain","phone","branchCount","firstSavedAt","lastSavedAt"]},"ResultCompanyListResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"companies":{"type":"array","items":{"$ref":"#/components/schemas/ResultCompany"}}},"required":["ok","companies"]},"ResultBranch":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public branch ID."},"resultId":{"type":"string","description":"Public search result ID that saved this branch."},"companyId":{"type":"string","description":"Public company ID."},"name":{"$ref":"#/components/schemas/NullableLocalizedText"},"address":{"$ref":"#/components/schemas/NullableLocalizedText"},"website":{"type":["string","null"],"description":"Branch website URL."},"phone":{"type":["string","null"],"description":"Branch phone number."},"lat":{"type":["number","null"],"description":"Branch latitude."},"lng":{"type":["number","null"],"description":"Branch longitude."},"rating":{"type":["number","null"],"description":"Branch public rating."},"reviews":{"type":["integer","null"],"description":"Branch public review count."},"location":{"$ref":"#/components/schemas/SearchResultLocation"}},"required":["id","resultId","companyId","name","address","website","phone","lat","lng","rating","reviews","location"]},"ResultBranchListResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"companyId":{"type":["string","null"],"description":"Present when branches are filtered to one company."},"branches":{"type":"array","items":{"$ref":"#/components/schemas/ResultBranch"}}},"required":["ok","branches"]},"ResultFolderPlacement":{"type":"object","additionalProperties":false,"properties":{"searchId":{"type":"string","description":"Public search ID."},"workspaceId":{"type":"string","description":"Public workspace ID."},"folderId":{"type":["string","null"],"description":"Public folder ID, or null when unfiled."},"updatedAt":{"type":"string","format":"date-time"}},"required":["searchId","workspaceId","folderId","updatedAt"]},"ResultMoveResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"placement":{"$ref":"#/components/schemas/ResultFolderPlacement"}},"required":["ok","placement"]},"ArchiveResultResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"search":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public search ID."},"deletedAt":{"type":"string","format":"date-time"}},"required":["id","deletedAt"]}},"required":["ok","search"]},"Folder":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public folder ID."},"name":{"type":"string","description":"Folder name."},"searchCount":{"type":"integer","description":"Number of saved searches in this folder."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","searchCount","createdAt","updatedAt"]},"FolderListResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"folders":{"type":"array","items":{"$ref":"#/components/schemas/Folder"}}},"required":["ok","folders"]},"FolderResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"folder":{"$ref":"#/components/schemas/Folder"}},"required":["ok","folder"]},"ArchiveFolderResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"folder":{"$ref":"#/components/schemas/Folder"},"deletedSearchCount":{"type":"integer","description":"Number of searches archived inside the folder."}},"required":["ok","folder","deletedSearchCount"]},"CreateFolderRequest":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":2,"maxLength":80,"description":"Folder name."}},"required":["name"]},"MoveResultToFolderRequest":{"type":"object","additionalProperties":false,"properties":{"folderId":{"type":["string","null"],"description":"Public folder ID, `unfiled`, or null to remove folder."}},"required":["folderId"]},"BranchList":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public Branch List ID."},"name":{"type":"string","description":"Workspace-visible List name."},"memberCount":{"type":"integer","description":"Current membership count."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","memberCount","createdAt","updatedAt"]},"BranchListListResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"lists":{"type":"array","items":{"$ref":"#/components/schemas/BranchList"}},"pagination":{"$ref":"#/components/schemas/ReferencePagination"}},"required":["ok","lists","pagination"]},"BranchListResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"list":{"$ref":"#/components/schemas/BranchList"}},"required":["ok","list"]},"ArchiveBranchListResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"list":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public Branch List ID."},"name":{"type":"string","description":"Archived List name."},"archivedAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","archivedAt","createdAt","updatedAt"]}},"required":["ok","list"]},"BranchListMemberBranch":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public Branch ID."},"name":{"$ref":"#/components/schemas/NullableLocalizedText"},"address":{"$ref":"#/components/schemas/NullableLocalizedText"},"website":{"type":["string","null"],"description":"Current Branch website, hidden when unavailable."},"phone":{"type":["string","null"],"description":"Current Branch phone, hidden when unavailable."},"categoryName":{"$ref":"#/components/schemas/NullableLocalizedText"},"countryCode":{"type":["string","null"],"description":"Current country code."},"countryName":{"$ref":"#/components/schemas/NullableLocalizedText"},"cityName":{"$ref":"#/components/schemas/NullableLocalizedText"},"districtName":{"$ref":"#/components/schemas/NullableLocalizedText"},"lat":{"type":["number","null"],"description":"Current Branch latitude, hidden when unavailable."},"lng":{"type":["number","null"],"description":"Current Branch longitude, hidden when unavailable."},"rating":{"type":["number","null"],"description":"Current Branch rating."},"reviews":{"type":["integer","null"],"description":"Current Branch review count."},"archivedAt":{"type":["string","null"],"description":"Branch archive timestamp, or null."},"updatedAt":{"type":"string","format":"date-time"},"company":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public Company ID."},"name":{"$ref":"#/components/schemas/NullableLocalizedText"},"archivedAt":{"type":["string","null"],"description":"Company archive timestamp, or null."}},"required":["id","name","archivedAt"]}},"required":["id","name","address","website","phone","categoryName","countryCode","countryName","cityName","districtName","lat","lng","rating","reviews","archivedAt","updatedAt","company"]},"BranchListMember":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public Branch List membership ID."},"branchId":{"type":"string","description":"Public Branch ID."},"position":{"type":"integer","description":"Stable zero-based manual position."},"createdAt":{"type":"string","format":"date-time"},"available":{"type":"boolean","description":"False when the Branch or Company is archived."},"branch":{"$ref":"#/components/schemas/BranchListMemberBranch"}},"required":["id","branchId","position","createdAt","available","branch"]},"BranchListMemberListResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"listId":{"type":"string","description":"Public Branch List ID."},"members":{"type":"array","items":{"$ref":"#/components/schemas/BranchListMember"}},"pagination":{"$ref":"#/components/schemas/ReferencePagination"}},"required":["ok","listId","members","pagination"]},"BranchListNameRequest":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","description":"Branch List name."}},"required":["name"]},"BranchIdsRequest":{"type":"object","additionalProperties":false,"properties":{"branchIds":{"type":"array","items":{"type":"string"},"description":"Public Branch IDs. Removal accepts at most 100; reorder requires every current member exactly once."}},"required":["branchIds"]},"AddBranchListMembersRequest":{"type":"object","additionalProperties":false,"properties":{"searchId":{"type":"string","description":"Public source Saved Search ID."},"branchIds":{"type":"array","items":{"type":"string"},"description":"Public Branch IDs visible within the source Saved Search. Maximum 100."}},"required":["searchId","branchIds"]},"AddBranchListMembersResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"list":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","description":"Public Branch List ID."},"name":{"type":"string","description":"Branch List name."},"addedCount":{"type":"integer","description":"New memberships created."},"alreadyPresentCount":{"type":"integer","description":"Existing memberships treated as no-ops."},"totalMemberCount":{"type":"integer","description":"Membership count after the request."}},"required":["id","name","addedCount","alreadyPresentCount","totalMemberCount"]}},"required":["ok","list"]},"RemoveBranchListMembersResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"removedCount":{"type":"integer","description":"Memberships removed."}},"required":["ok","removedCount"]},"ReorderBranchListMembersResponse":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":true},"reorderedCount":{"type":"integer","description":"Memberships reordered."}},"required":["ok","reorderedCount"]},"Error":{"type":"object","additionalProperties":false,"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","description":"Stable error code."},"message":{"type":"string","description":"Human-readable error message."},"details":{"type":"object","additionalProperties":true}},"required":["code","message"]}},"required":["ok","error"]}}},"x-microscope-api-scopes":["workspaceRead","referenceRead","searchesRead","searchesWrite","resultsRead","resultsWrite","foldersRead","foldersWrite","listsRead","listsWrite"]}