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