DocsAPI Reference

Mira API Documentation

The Mira API empowers developers with AI-driven talent intelligence. Search global candidate, job, and scholar datasets, grade CVs, look up entity details, and integrate with MCP-compatible assistants.

Overview

The Mira API provides a comprehensive set of endpoints for talent intelligence. All requests are authenticated using Bearer tokens (API keys that start with mira_).

The API supports both direct REST calls and the Model Context Protocol (MCP), enabling integration with AI assistants like Claude. Current API version: 2.1.0.

Host	URL	Use
Production API	https://mira-api.openjobs-ai.com	REST and MCP calls
Platform dashboard	https://platform.openjobs-ai.com	Sign in, create API keys, manage usage and quota

Note

Mira API 2.1.0 uses an ID-first search model: people and job search endpoints return string type IDs, then clients fetch full documents through /entity/v1/... detail endpoints. Omit country filters to search the global dataset.

Latest Version Summary

Current version: 2.1.0. Previous documented version: 2.0.1. See the full update log for version history and version-to-version changes.

Response formatting was cleaned up for a simpler, consistent envelope.
People and job search ID types are updated to string IDs across search results and entity detail lookups.
Public search result windows are adjusted to 100 results per request.
Scholar search result sizing is updated to support explicit size values up to 100.
Job detail and _source selection now follow public detail field defaults for public API keys.
GET /v1/version is supported alongside GET /version.

System

Use system routes to check the deployed API version and the authenticated API key status.

Version

bash

curl -s https://mira-api.openjobs-ai.com/version

json

{
  "code": 200,
  "msg": "ok",
  "data": {
    "version": "2.1.0"
  }
}

API Key Status

bash

curl -X GET "https://mira-api.openjobs-ai.com/auth/key/status" \
  -H "Authorization: Bearer $MIRA_KEY"

Response data includes key_id, key_prefix, user_id, active, scopes, rpm_limit, quota_total, quota_used, quota_remaining, and expires_at.

Quick Start: Agent-Skills

The fastest way to use the Mira API is through OpenClaw Skills — Markdown-based instruction files that give your AI assistant (Claude, GPT, Gemini, etc.) full access to talent search, grading, and enrichment directly from the chat interface. No boilerplate. No manual tool wiring.

OpenJobsAI / openjobs-openclaw-skills

github.com/OpenJobsAI/openjobs-openclaw-skills

View on GitHub

Available Skills

openjobs-people-search

ClawhHub

Search, discover, and retrieve professional candidate profiles

·Structured search with explicit filters
·Profile lookup by LinkedIn URL
·Side-by-side candidate comparison
·Talent pool analytics
·Unlock contact emails

openjobs-people-match

ClawhHub

Evaluate candidate-job fit with AI scoring

·Grade a single CV against a JD (0–100)
·Bulk-grade up to 20 candidates
·Ranked results by fit score

Installation

npx — recommended

bash

npx skills install OpenJobsAI/openjobs-openclaw-skills

OpenClaw / ClawhHub

Inside any OpenClaw-compatible agent, say Install skills: OpenJobsAI/openjobs-openclaw-skills to install both skills at once. Or install individually via ClawhHub:

bash

clawhub install openjobs-people-search
clawhub install openjobs-people-match

Claude Code

bash

# Via terminal
claude plugin marketplace add OpenJobsAI/openjobs-openclaw-skills

# Inside the chat
/plugin marketplace add OpenJobsAI/openjobs-openclaw-skills

Authentication

After installation, set your MIRA_KEY environment variable so the skill can authenticate automatically:

bash

export MIRA_KEY="mira_xxxxxxxxxxxx"

Get your key from the API Keys page. The skill reads $MIRA_KEY from the environment and passes it automatically as a Bearer token on every request.

Tip

Prefer MCP for deeper tool integration with your agent? See the section for Streamable HTTP and SSE transport options.

Quick Start: Direct API Call

Prefer calling the REST API directly? Set $MIRA_KEY to your API key, then make your first request:

bash

export MIRA_KEY="mira_xxxxxxxxxxxx"

curl -X POST "https://mira-api.openjobs-ai.com/v1/people-grade" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cv": "10 years Python backend development, AWS certified",
    "jd": "Senior Python engineer with cloud experience"
  }'

All responses follow a unified envelope format:

json

{ "code": 200, "msg": "ok", "data": { ... } }

Note

Error responses use the same format with non-200 codes and "data": null. For example: { "code": 401, "msg": "API key not found", "data": null }

Authentication

All requests must include your API key as a Bearer token in the Authorization header:

bash

curl -X POST "https://mira-api.openjobs-ai.com/v1/..." \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json"

Header	Value	Description
Authorization	Bearer $MIRA_KEY	Required. Your Mira API key (starts with mira_)
Content-Type	application/json	Required for all POST requests with a body

Tip

Manage and rotate your API keys from the API Keys page in the dashboard.

Natural Language People Search

POST/v1/people-search

Natural-language candidate search. Mira converts the request into a controlled, policy-filtered search over approved public profile fields and returns profile IDs only.

Request Parameters

Parameter	Type	Required	Description
text	string (1-5000 chars)	Yes	Natural-language people search query
size	integer (1-100)	No	Maximum profile IDs to return. Defaults to 100

bash

curl -X POST "https://mira-api.openjobs-ai.com/v1/people-search" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "search all us data engineers",
    "size": 100
  }'

Response Example

json

{
  "code": 200,
  "msg": "ok",
  "data": {
    "profile_ids": ["PavstrIWX_ZuAc2AOAZXHA", "ItGafMDFS3n8phCHDDyvEA"]
  }
}

Tip

Use /entity/v1/profiles/detail-by-id after search to fetch full profile documents. For structured filters, use /v1/people-fast-search.

Search Candidates

POST/v1/people-fast-search

Structured field search that bypasses AI parsing for faster results. It returns string profile IDs only. At least one search filter is required. Returns up to 100 profile IDs for public API keys.

Request Parameters

All filter fields are optional, but at least one search condition must be provided. size controls result count and does not count as a search condition.

Basic Info

Parameter	Type	Description
size	integer (1-100)	Maximum profile IDs to return. Defaults to 100
full_name	string (max 200)	Full name (exact match)
headline	string (max 200)	Professional headline (fuzzy match)
is_working	boolean	Currently employed (exact match)
is_decision_maker	boolean	Is a decision maker

Location

Parameter	Type	Description
country	string (max 100)	Country (exact match). Use full name: "United States" not "US"
city	string (max 100)	City name (exact match)
state	string (max 100)	State or province (exact match). Use full name: "California" not "CA"

Current Position

Parameter	Type	Description
active_title	string (max 200)	Current job title (fuzzy match)
management_level	string (max 50)	Management level (exact match). See valid values
active_department	string (max 200)	Current department (fuzzy match)

Work Experience

Parameter	Type	Description
experience_months_min	integer (≥0)	Minimum total experience (months)
experience_months_max	integer (≥0)	Maximum total experience (months)
company_name	string (max 200)	Company name (phrase match)
industry	string (max 100)	Industry (exact match). See valid values
company_type	string (max 50)	Company type (exact match). See valid values
level	string (max 50)	Seniority level (exact match). See valid values
role	string (max 50)	Role type (exact match). See valid values
skills	string[] (max 20 items)	Required skills list
skills_operator	string	Skill matching logic: AND or OR (default: AND)
certifications	string (max 200)	Certifications (fuzzy match, e.g. "AWS", "PMP")
languages	string[] (max 20 items)	Required languages (all must match)

Education

Parameter	Type	Description
degree_level_min	integer (≥0)	Minimum degree level
institution_name	string (max 200)	Institution name (fuzzy match)
major	string (max 200)	Major or field of study (fuzzy match)
institution_ranking_max	integer (≥1)	Max institution ranking (e.g. 100 = Top 100)

Note

For all valid enum values (role, level, industry, company_type), see the .

bash

curl -X POST "https://mira-api.openjobs-ai.com/v1/people-fast-search" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "United States",
    "skills": ["Python", "AWS"],
    "skills_operator": "AND",
    "experience_months_min": 60,
    "is_working": true,
    "size": 100
  }'

Response Example

json

{
  "code": 200,
  "msg": "ok",
  "data": {
    "profile_ids": ["PavstrIWX_ZuAc2AOAZXHA", "ItGafMDFS3n8phCHDDyvEA"]
  }
}

Note

Fetch full profile records with /entity/v1/profiles/detail-by-id. Entity detail endpoints accept up to 50 string type IDs or LinkedIn URLs per request.

HTTP Status	Reason
400	No filter condition provided
422	Invalid parameter format or value

Profile Details

POST/entity/v1/profiles/detail-by-id

Fetch full candidate profile documents after search returns string profile IDs. Detail endpoints are capped at 50 string type IDs or LinkedIn URLs per request so clients can batch and page explicitly.

Lookup by Profile ID

Parameter	Type	Required	Description
profile_ids	string[] (1-50 items)	Yes	String profile IDs returned by people search endpoints
_source / source	array, object, or boolean	No	Elasticsearch source selection. Defaults to Mira profile detail fields

bash

curl -X POST "https://mira-api.openjobs-ai.com/entity/v1/profiles/detail-by-id" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_ids": ["PavstrIWX_ZuAc2AOAZXHA", "ItGafMDFS3n8phCHDDyvEA"],
    "_source": ["profile_id", "full_name", "active_experience_title", "address", "skills"]
  }'

Lookup by LinkedIn URL

POST/entity/v1/profiles/detail-by-linkedin-url

Parameter	Type	Required	Description
linkedin_urls	string[] (1-50 items)	Yes	LinkedIn profile URLs to fetch
_source / source	array, object, or boolean	No	Elasticsearch source selection. Defaults to Mira profile detail fields

bash

curl -X POST "https://mira-api.openjobs-ai.com/entity/v1/profiles/detail-by-linkedin-url" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_urls": ["https://www.linkedin.com/in/xxx"],
    "_source": ["profile_id", "full_name", "address", "active_experience_title"]
  }'

Response Example

json

{
  "code": 200,
  "msg": "ok",
  "data": {
    "total": 2,
    "found": 1,
    "not_found": ["ItGafMDFS3n8phCHDDyvEA"],
    "results": [
      {
        "profile_id": "PavstrIWX_ZuAc2AOAZXHA",
        "full_name": "Jane Doe",
        "active_experience_title": "Data Engineer",
        "address": { "state": "California", "country": "United States" },
        "skills": ["python", "sql", "aws"]
      }
    ]
  }
}

Grade Candidate

POST/v1/people-grade

Submit a candidate CV and job description. AI evaluates the match and returns a score (0–100) with reasoning.

Request Parameters

Parameter	Type	Required	Description
cv	string (1–5000 chars)	Yes	Candidate resume text
jd	string (1–5000 chars)	Yes	Job description text

bash

curl -X POST "https://mira-api.openjobs-ai.com/v1/people-grade" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cv": "10 years Python backend development...",
    "jd": "Senior Python engineer with cloud experience..."
  }'

Response Example

json

{
  "code": 200,
  "msg": "ok",
  "data": {
    "total_score": {
      "rating": 85,
      "description": "- Strong Python background with 10+ years directly matching the requirement.\n- Extensive backend and cloud experience aligns well with the role.\n- Financial services exposure is an added advantage."
    }
  }
}

Note

rating is an integer from 0 to 100. description contains the AI reasoning behind the score.

Analytics

POST/v1/people-stats

Aggregate analytics on the candidate database. Supports group-by counts, numeric statistics (min/max/avg/sum), and histogram bucketing. At least one of group_by, stats_fields, or histogram_fields must be provided.

Request Parameters

All are supported for narrowing the dataset, excluding search-only size. Additionally, at least one aggregation field is required:

Parameter	Type	Limit	Description
group_by	string[]	max 5	Group by dimension and count results
stats_fields	string[]	max 3	Numeric statistics: min/max/avg/sum
histogram_fields	object[]	max 2	Histogram bucketing by interval

The histogram_fields object accepts:

Field	Type	Description
field	string	Field name to bucket (e.g. experience_months)
interval	integer	Bucket size (optional; defaults vary by field)

Note

See for all available group_by dimensions, stats_fields, and histogram_fields.

bash

curl -X POST "https://mira-api.openjobs-ai.com/v1/people-stats" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "United States",
    "group_by": ["management_level"],
    "stats_fields": ["experience_months"]
  }'

Response Example

json

{
  "code": 200,
  "msg": "ok",
  "data": {
    "total_matched": 10000,
    "aggregations": {
      "management_level": [
        { "key": "Specialist", "count": 3800000 },
        { "key": "Manager",    "count": 720000  },
        { "key": "Senior",     "count": 445000  },
        { "key": "Director",   "count": 330000  }
      ],
      "experience_months_stats": {
        "min": 0, "max": 480, "avg": 96.3, "sum": 700000000
      }
    }
  }
}

Compare Candidates

POST/v1/people-compare

Compare multiple candidates side by side. Returns structured data including current position, highest education, skills, and languages.

Request Parameters

Parameter	Type	Required	Description
linkedin_urls	string[] (2–10 items)	Yes	LinkedIn URLs of candidates to compare

bash

curl -X POST "https://mira-api.openjobs-ai.com/v1/people-compare" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_urls": [
      "https://www.linkedin.com/in/xxx",
      "https://www.linkedin.com/in/yyy"
    ]
  }'

Response Example

json

{
  "code": 200,
  "msg": "ok",
  "data": {
    "total_requested": 2,
    "total_found": 2,
    "not_found": [],
    "comparisons": [
      {
        "linkedin_url": "https://www.linkedin.com/in/xxx",
        "full_name": "Jane Doe",
        "headline": "Senior Python Engineer | Backend | Cloud",
        "location": { "country": "United States", "city": "San Francisco" },
        "is_working": true,
        "total_experience_months": 120,
        "current_position": {
          "title": "Senior Software Engineer",
          "company": "Acme Corp",
          "industry": "Software Development"
        },
        "highest_education": {
          "degree": "Bachelor of Science, Computer Science",
          "institution": "State University",
          "major": "Computer Science"
        },
        "skills": ["python", "fastapi", "postgresql", "docker", "aws"],
        "languages": ["English"],
        "is_decision_maker": false
      },
      {
        "linkedin_url": "https://www.linkedin.com/in/yyy",
        "full_name": "John Smith",
        "headline": "Backend Engineer | Python | AWS",
        "location": { "country": "United States", "city": "Austin" },
        "is_working": true,
        "total_experience_months": 144,
        "current_position": {
          "title": "Senior Backend Engineer",
          "company": "Tech Solutions Inc",
          "industry": "IT Services and IT Consulting"
        },
        "highest_education": {
          "degree": "Bachelor of Engineering, Computer Science",
          "institution": "University of Technology",
          "major": "Computer Science"
        },
        "skills": ["python", "aws", "docker", "postgresql", "kubernetes"],
        "languages": ["English"],
        "is_decision_maker": false
      }
    ]
  }
}

Bulk Grade

POST/v1/people-bulk-grade

Grade multiple candidates against a single job description in one request. Results are sorted by score in descending order.

Request Parameters

Parameter	Type	Required	Description
linkedin_urls	string[] (1–20 items)	Yes	Candidate LinkedIn URLs to grade
jd	string (10–5000 chars)	Yes	Job description text

Note

Concurrency limit: up to 5 simultaneous AI grading requests per call.

bash

curl -X POST "https://mira-api.openjobs-ai.com/v1/people-bulk-grade" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_urls": [
      "https://www.linkedin.com/in/xxx",
      "https://www.linkedin.com/in/yyy"
    ],
    "jd": "Senior Python Engineer with 5+ years experience in backend development and AWS..."
  }'

Response Example

json

{
  "code": 200,
  "msg": "ok",
  "data": {
    "jd_preview": "Senior Python Engineer with 5+ years experience in backend development and AWS...",
    "total_requested": 2,
    "total_graded": 2,
    "total_failed": 0,
    "not_found": [],
    "rankings": [
      {
        "linkedin_url": "https://www.linkedin.com/in/xxx",
        "total_score": {
          "rating": 92,
          "description": "- Strong Python background with 10+ years directly matching the requirement.\n- Extensive backend and AWS experience aligns well with the role."
        },
        "error": null
      },
      {
        "linkedin_url": "https://www.linkedin.com/in/yyy",
        "total_score": {
          "rating": 74,
          "description": "- Meets the Python experience requirement.\n- AWS and DevOps skills are relevant but backend focus is less prominent."
        },
        "error": null
      }
    ]
  }
}

Note

If grading fails for a candidate, total_score will be null, error will contain the error message, and the entry will appear at the bottom of the rankings list.

Unlock Contacts

POST/v1/people-unlock

Retrieve email contact information for candidates by LinkedIn URL. Each URL consumes 200 quota points. Quota is checked and deducted atomically in a single operation.

Request Parameters

Parameter	Type	Required	Description
linkedin_urls	string[] (1-50 items)	Yes	LinkedIn URLs to unlock. Each URL costs 200 quota points.

Warning

The entire batch is rejected with HTTP 402 if you have insufficient quota. Check your remaining quota before submitting large batches.

bash

curl -X POST "https://mira-api.openjobs-ai.com/v1/people-unlock" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_urls": [
      "https://www.linkedin.com/in/xxx",
      "https://www.linkedin.com/in/yyy"
    ]
  }'

Response Example

json

{
  "code": 200,
  "msg": "ok",
  "data": {
    "list": [
      {
        "linkedinUrl": "https://www.linkedin.com/in/xxx",
        "personEmail": "jane.doe@gmail.com",
        "workEmail": "jane.doe@acme.com"
      },
      {
        "linkedinUrl": "https://www.linkedin.com/in/yyy",
        "personEmail": "john.smith@gmail.com",
        "workEmail": null
      }
    ]
  }
}

HTTP Status	Reason
402	Insufficient quota (need N points, have M)

Search Jobs

POST/v1/job-fast-search

Structured field search for job positions. Queries the job database directly and returns string job IDs only. At least one filter field is required. Returns up to 100 job IDs for public API keys. Only active, non-deleted jobs are returned.

Request Parameters

All filter fields are optional, but at least one search condition must be provided. size controls result count and does not count as a search condition.

Parameter	Type	Description
size	integer (1-100)	Maximum job IDs to return. Defaults to 100
title	string (max 200)	Job title (fuzzy match)
description	string (max 500)	Job description keywords (fuzzy match)
company_name	string (max 200)	Company name (phrase match)
seniority	string (max 100)	Seniority level (exact match, e.g. "Entry level", "Mid-Senior level")
employment_type	string (max 100)	Employment type (exact match, e.g. "Full-time", "Part-time")
location	string (max 200)	Job location (exact match)
country	string (max 100)	Country (exact match)
industry	string (max 200)	Industry (exact match)
function	string (max 200)	Job function (fuzzy match)
time_posted_from	string (ISO 8601)	Posted after (e.g. "2025-01-01")
time_posted_to	string (ISO 8601)	Posted before (e.g. "2025-12-31")

bash

curl -X POST "https://mira-api.openjobs-ai.com/v1/job-fast-search" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Python Engineer",
    "country": "United States",
    "employment_type": "Full-time",
    "seniority": "Mid-Senior level",
    "size": 100
  }'

Response Example

json

{
  "code": 200,
  "msg": "ok",
  "data": {
    "job_ids": ["01CWlhuF85DP45jLrytvOw", "0FVdRCfvTIaZPxHk25jMeA"]
  }
}

Note

Fetch full job records with /entity/v1/jobs/detail-by-id. The detail endpoint accepts up to 50 string job IDs per request.

Job Detail by ID

POST/entity/v1/jobs/detail-by-id

Parameter	Type	Required	Description
job_ids	string[] (1-50 items)	Yes	String job IDs returned by job search
_source / source	array, object, or boolean	No	Elasticsearch source selection. Defaults to public job detail fields

bash

curl -X POST "https://mira-api.openjobs-ai.com/entity/v1/jobs/detail-by-id" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_ids": ["01CWlhuF85DP45jLrytvOw", "0FVdRCfvTIaZPxHk25jMeA"],
    "_source": ["uu_job_id", "title", "company_name", "location", "experience_level"]
  }'

HTTP Status	Reason
400	No filter condition provided
422	Invalid parameter format or value

Search Scholars

POST/v1/scholar-fast-search

Structured field search for academic scholars. At least one filter field is required. Returns up to 100 results for public API keys. Sensitive fields (email, phone, internal IDs) are excluded from the response.

Request Parameters

All fields are optional, but at least one must be provided.

Basic Info & Location

Parameter	Type	Description
full_name	string (max 200)	Full name (exact match)
size	integer (1-100)	Maximum scholar profiles to return. Defaults to 100
headline	string (max 200)	Professional headline (fuzzy match)
country	string (max 100)	Country (exact match)
city	string (max 100)	City (exact match)

Position & Affiliation

Parameter	Type	Description
current_position	string (max 200)	Current position title (fuzzy match)
current_position_type	string (max 100)	Current position type (exact match)
active_title	string (max 200)	Active experience title (fuzzy match)
management_level	string (max 50)	Management level (exact match)
affiliations	string (max 200)	Affiliated institution/organization (fuzzy match)

Research Areas & Skills

Parameter	Type	Description
areas	string[] (max 20 items)	Research areas
areas_operator	string	Area matching logic: AND or OR (default: AND)
skills	string[] (max 20 items)	Skills
skills_operator	string	Skill matching logic: AND or OR (default: AND)

Academic Metrics

Parameter	Type	Description
total_citations_min	integer (≥0)	Minimum total citations
total_citations_max	integer (≥0)	Maximum total citations
h_index_min	integer (≥0)	Minimum h-index (all time)

Education & Articles

Parameter	Type	Description
university	string (max 200)	University name (fuzzy match)
major	string (max 200)	Major or field of study (fuzzy match)
degree_level_min	integer (≥0)	Minimum degree level
article_title	string (max 500)	Article title keyword (fuzzy match)
article_publication	string (max 200)	Publication/journal name (fuzzy match)
experience_months_min	integer (≥0)	Minimum total experience in months
experience_months_max	integer (≥0)	Maximum total experience in months

bash

curl -X POST "https://mira-api.openjobs-ai.com/v1/scholar-fast-search" \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "areas": ["Machine Learning", "Natural Language Processing"],
    "areas_operator": "AND",
    "country": "United States",
    "h_index_min": 20,
    "size": 100
  }'

Response Example

json

{
  "code": 200,
  "msg": "ok",
  "data": [
    {
      "full_name": "Dr. Jane Smith",
      "headline": "Associate Professor of Computer Science",
      "location_struct": {
        "country": "United States",
        "city": "Stanford"
      },
      "current_position": "Associate Professor",
      "current_position_type": "Faculty",
      "affiliations": "Stanford University",
      "areas": ["Machine Learning", "Natural Language Processing", "Deep Learning"],
      "skills": ["Python", "TensorFlow", "PyTorch"],
      "total_citations": 15200,
      "h_index": { "all": 42 },
      "education": [
        {
          "university": "MIT",
          "major": "Computer Science",
          "degree_level": 3
        }
      ],
      "articles": [
        {
          "title": "Attention Mechanisms in Neural Networks",
          "publication": "NeurIPS 2023"
        }
      ]
    }
  ]
}

Note

data is a direct array of scholar profiles, up to 100 results for public API keys.

HTTP Status	Reason
400	No filter condition provided
422	Invalid parameter format or value

OpenJobs CLI

Deprecated

OpenJobs CLI is no longer maintained

No active maintenance

The CLI package is kept here as a deprecated reference only. New integrations should use the REST API, MCP Protocol, or OpenJobs agent skills.

Package	Status	Recommended path
@openjobs-ai/cli	Deprecated; no longer maintained	Use REST API, MCP Protocol, or agent skills

MCP Protocol

The Mira API supports the Model Context Protocol (MCP), enabling direct integration with AI assistants like Claude.

Transport	URL	Protocol Version
Streamable HTTP	https://mira-api.openjobs-ai.com/mcp	MCP 2025-03-26
SSE (legacy)	https://mira-api.openjobs-ai.com/sse	MCP 2024-11-05

Initialize MCP Session

bash

curl -X POST https://mira-api.openjobs-ai.com/mcp \
  -H "Authorization: Bearer $MIRA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "1.0" }
    }
  }'

Claude Code Setup

Connect the Mira API to Claude Code as an MCP server:

bash

claude mcp add --scope user --transport http \
  mira-api-http \
  https://mira-api.openjobs-ai.com/mcp \
  --header "Authorization: Bearer $MIRA_KEY"

Tip

Use --scope project instead of --scope user to restrict the server to the current project only.

Claude Desktop

Add the Mira API to your claude_desktop_config.json to use Mira tools directly inside Claude Desktop:

json

{
  "mcpServers": {
    "mira-api": {
      "url": "https://mira-api.openjobs-ai.com/mcp",
      "headers": {
        "Authorization": "Bearer $MIRA_KEY"
      }
    }
  }
}

Note

Replace $MIRA_KEY with your actual API key value in the config file.

Search Filters Reference

Exact match enum values for the endpoint. These strings must be passed exactly as listed.

Valid values for `role`

text

Administrative, C-Suite, Consulting, Customer Service, Design, Education,
Engineering and Technical, Finance & Accounting, Human Resources, Legal,
Marketing, Medical, Operations, Other, Product, Project Management,
Real Estate, Research, Sales, Trades

Valid values for `level`

text

C-Level, Director, Founder, Head, Intern, Manager, Owner, Partner,
President/Vice President, Senior, Specialist

Valid values for `company_type`

text

Educational, Government Agency, Nonprofit, Partnership,
Privately Held, Public Company, Self-Employed, Self-Owned

Valid values for `industry`

text

Accommodation Services, Administrative and Support Services, Construction,
Consumer Services, Education, Entertainment Providers,
Farming, Ranching, Forestry, Financial Services, Government Administration,
Holding Companies, Hospitals and Health Care, Manufacturing,
Oil, Gas, and Mining, Professional Services,
Real Estate and Equipment Rental Services, Retail,
Technology, Information and Media,
Transportation, Logistics, Supply Chain and Storage,
Utilities, Wholesale

Analytics Fields Reference

Available fields for the endpoint aggregation parameters.

Available `group_by` dimensions

text

country, city, state,
active_title, active_department, management_level,
job_title, company_name, industry, company_type, level, role,
exp_country, exp_city,
degree_level, degree_str, institution_name, major, institution_country, institution_city,
skills, is_working, is_decision_maker, languages

Available `stats_fields`

text

experience_months, exp_duration, gpa, institution_ranking, company_employees_count

Available `histogram_fields`

Field	Default Interval
experience_months	12
institution_ranking	50

Error Codes

All error responses use the unified format: { "code": 4xx/5xx, "msg": "<error message>", "data": null }

HTTP Status	code	Description
400	400	Invalid or missing request parameters
401	401	Missing or invalid Authorization header / API key not found
402	402	Quota exhausted (need N points, have M)
403	403	API key disabled, expired, or insufficient scope
404	404	Route not found
422	422	Invalid parameter format or value
429	429	Rate limit exceeded (RPM)
503	503	Feature unavailable
500	500	Internal server error

Sunset Adjustments

These older public workflows are tracked as sunset adjustments in Mira API 2.1.0. Use the replacement route shown below.

Sunset adjustment	Replacement
POST /v1/people-search/profile-ids	POST /v1/people-search
POST /v1/people-search/profiles	POST /v1/people-search, then POST /entity/v1/profiles/detail-by-id
POST /v1/people-lookup	POST /entity/v1/profiles/detail-by-linkedin-url

Mira API Documentation

Overview

Latest Version Summary

System

Version

API Key Status

Quick Start: Agent-Skills

Available Skills

Installation

Authentication

Quick Start: Direct API Call

Authentication

Natural Language People Search

Request Parameters

Response Example

Search Candidates

Request Parameters

Response Example

Profile Details

Lookup by Profile ID

Lookup by LinkedIn URL

Response Example

Grade Candidate

Request Parameters

Response Example

Analytics

Request Parameters

Response Example

Compare Candidates

Request Parameters

Response Example

Bulk Grade

Request Parameters

Response Example

Unlock Contacts

Request Parameters

Response Example

Search Jobs

Request Parameters

Response Example

Job Detail by ID

Search Scholars

Request Parameters

Response Example

OpenJobs CLI

MCP Protocol

Initialize MCP Session

Claude Code Setup

Claude Desktop

Search Filters Reference

Valid values for role

Valid values for level

Valid values for company_type

Valid values for industry

Analytics Fields Reference

Available group_by dimensions

Available stats_fields

Available histogram_fields

Error Codes

Sunset Adjustments

Valid values for `role`

Valid values for `level`

Valid values for `company_type`

Valid values for `industry`

Available `group_by` dimensions

Available `stats_fields`

Available `histogram_fields`