# Mjhr API

Use the Mjhr API to read workspace metadata, submit and read saved searches, read result companies and branches, move or archive result sets, create or archive folders, and curate reusable Branch Lists.

## Authentication

Send a scoped API key in the Authorization header: `Authorization: Bearer <API_KEY>`.

## Base URLs

- API service: https://api.mjhr.ai/v1
- OpenAPI: https://help.mjhr.ai/openapi.json
- MCP endpoint: https://help.mjhr.ai/mcp
- Full API context: https://help.mjhr.ai/api/llms-full.txt

## Scopes

- `workspaceRead`
- `referenceRead`
- `searchesRead`
- `searchesWrite`
- `resultsRead`
- `resultsWrite`
- `foldersRead`
- `foldersWrite`
- `listsRead`
- `listsWrite`

## Endpoint Inventory

| Method | Path | Operation | Purpose |
| --- | --- | --- | --- |
| GET | /v1/workspace | get_workspace | Get workspace metadata |
| GET | /v1/countries | list_countries | List Search country references |
| GET | /v1/cities | list_cities | List Search city references |
| GET | /v1/cities/{cityId} | get_city | Get a Search city reference |
| GET | /v1/cities/{cityId}/districts | list_city_districts | List city district references |
| GET | /v1/categories | list_categories | List Search category references |
| GET | /v1/searches | list_searches | List saved searches |
| POST | /v1/searches | create_search | Submit a new saved search |
| GET | /v1/searches/{searchId} | get_search | Get a saved search |
| GET | /v1/searches/{searchId}/results | list_search_results | List saved search results |
| GET | /v1/results/{searchId} | list_result_companies | List result companies |
| GET | /v1/results/{searchId}/branches | list_result_branches | List result branches |
| GET | /v1/results/{searchId}/{companyId} | list_company_result_branches | List one result company’s branches |
| POST | /v1/results/{searchId}/folder | move_result_to_folder | Move a result set to a folder |
| POST | /v1/results/{searchId}/archive | archive_result_set | Archive a result set |
| GET | /v1/folders | list_folders | List search-history folders |
| POST | /v1/folders | create_folder | Create a search-history folder |
| POST | /v1/folders/{folderId}/archive | archive_folder | Archive a search-history folder |
| GET | /v1/lists | list_branch_lists | List active Branch Lists |
| POST | /v1/lists | create_branch_list | Create a Branch List |
| GET | /v1/lists/{listId} | get_branch_list | Get Branch List metadata |
| POST | /v1/lists/{listId}/rename | rename_branch_list | Rename a Branch List |
| POST | /v1/lists/{listId}/archive | archive_branch_list | Archive a Branch List |
| GET | /v1/lists/{listId}/members | list_branch_list_members | List Branch List members |
| POST | /v1/lists/{listId}/members | add_branch_list_members | Add Branches to a List |
| POST | /v1/lists/{listId}/members/remove | remove_branch_list_members | Remove Branches from a List |
| POST | /v1/lists/{listId}/order | reorder_branch_list_members | Replace Branch List order |

## Result nesting

- `GET /v1/results/{searchId}` returns companies.
- `GET /v1/results/{searchId}/branches` returns all branches for those companies.
- `GET /v1/results/{searchId}/{companyId}` returns branches for one company.
- Result moves and result archives require `resultsWrite`; folder archives require `foldersWrite`.
- Branch List reads require `listsRead`; lifecycle and atomic membership mutations require `listsWrite`.