# 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`.

## Relevant Help Pages

# Create a safe API key

Give another system only the Mjhr access it needs, then keep the token private.

Canonical URL: https://help.mjhr.ai/api-authentication
Machine-readable page: https://help.mjhr.ai/api-authentication/README.md
Full help context: https://help.mjhr.ai/llms-full.txt
Audience: Developers

## Before you create a key

Create API keys from the dashboard integration settings. Each key belongs to one workspace, so the key can only access data from that workspace.

Copy the generated token when it is shown and store it in a server-side secret manager. Do not place it in browser code, client-side config, generated files, or chat logs.

- Know which workspace the integration should read from.
- Choose the smallest set of scopes needed for the job.
- Name the key after the system or workflow that will use it.
- Plan how you will rotate or revoke the key if access changes.

## Choose access

- Workspace read: lets the integration confirm workspace identity, plan, and usage.
- Searches read: lets it list saved searches and fetch one saved search.
- Searches write: lets it submit new saved searches through the public API.
- Results read: lets it read companies first, then branches through the nested results endpoints.
- Results write: lets it move a result set to a folder or archive that result set.
- Folders read: lets it list search-history folders.
- Folders write: lets it create and archive folders, including archiving the searches inside a folder.

Note: Read-only agents usually need workspace read, searches read, results read, and folders read. Add write scopes only when the user expects the tool to create searches, move/archive result sets, or create/archive folders.

## Send requests securely

Send the token on each request with the Authorization header.

### Authorization header

```http
Authorization: Bearer <API_KEY>
```

## Allowed origins

API keys can be restricted by allowed origins. Server-side integrations usually do not need a browser origin. Browser-facing tools should call your backend first so the API key stays private.

---

# Use the public API

Read workspace, saved search, result, and folder data from Mjhr.

Canonical URL: https://help.mjhr.ai/api-reference
Machine-readable page: https://help.mjhr.ai/api-reference/README.md
Full help context: https://help.mjhr.ai/llms-full.txt
Audience: Developers

## What the API is for

The public API is for tools that need to read Mjhr workspace data outside the dashboard. It covers workspace metadata, saved searches, saved search results, folders, and folder creation.

Use the OpenAPI document as the source of truth for request parameters, response fields, and the current server URL.

## Start with these resources

- [OpenAPI document](https://help.mjhr.ai/openapi.json)
  OpenAPI 3.1 contract generated from the API package.
- [API LLM context](https://help.mjhr.ai/api/llms.txt)
  Concise agent-readable API guide.

## Current endpoints

- GET /v1/workspace checks which workspace the key belongs to and returns plan usage.
- GET /v1/searches lists saved searches visible to the key.
- GET /v1/searches/{searchId} returns one saved search and its filters.
- GET /v1/searches/{searchId}/results lists the companies and branches saved under that search.
- GET /v1/folders lists search-history folders.
- POST /v1/folders creates a search-history folder.

## Typical read flow

- Confirm the workspace: Call /v1/workspace so the integration can show which workspace it is using before reading data.
- List saved searches: Call /v1/searches to let the user choose the list they want to work with.
- Fetch results: Call /v1/searches/{searchId}/results after the user or workflow chooses a saved search.
- Use folders when helpful: Call /v1/folders to show organization context, or POST /v1/folders when the integration needs to create a new folder.

Note: Use public IDs returned by the API in future calls. Do not construct IDs from database prefixes or internal table names.

---

# Connect an AI agent

Help an agent discover Mjhr safely before it reads workspace data.

Canonical URL: https://help.mjhr.ai/agent-integration
Machine-readable page: https://help.mjhr.ai/agent-integration/README.md
Full help context: https://help.mjhr.ai/llms-full.txt
Audience: Agents

## What an agent needs

An agent should not guess how Mjhr works. It should read the product help, load the API contract, ask for a scoped credential when needed, and confirm the workspace or saved search before using data.

The help package exposes human-readable pages and machine-readable resources so agents can start with the same source of truth as users and developers.

## Discovery order

- Read llms.txt: Start at /llms.txt for the concise product map and links to deeper context.
- Fetch OpenAPI: Use /openapi.json as the canonical HTTP contract before constructing requests.
- Use MCP when available: Call /mcp when your runtime supports MCP tools. The tools mirror OpenAPI operations and delegate to the existing API.
- Ask for missing credentials: Do not invent API keys. Ask the user to provide a scoped key or connect a secret store.
- Confirm before using data: Show the workspace and saved search that will be queried before using results for analysis, outreach, or export workflows.

## MCP request shape

The MCP endpoint speaks JSON-RPC over HTTP. Send Authorization on the MCP request; tool calls forward that header to the API service.

### List tools

```json
{
  "jsonrpc": "2.0",
  "id": "tools",
  "method": "tools/list"
}
```

### Call a read-only tool

```json
{
  "jsonrpc": "2.0",
  "id": "searches",
  "method": "tools/call",
  "params": {
    "name": "list_searches",
    "arguments": {
      "query": { "limit": 25 }
    }
  }
}
```

## Agent safety boundaries

- Treat API keys as secrets and avoid writing them into generated files or logs.
- Prefer read-only scopes unless the user explicitly asks the agent to create folders.
- Explain which workspace and saved search will be queried before using results.
- Use public IDs returned by the API, not internal database IDs.

---