DocsAPI Reference

Mira API Documentation

The Mira API empowers developers with AI-driven talent intelligence. Search candidates, grade CVs, look up profiles, 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 seamless integration with AI assistants like Claude. Base URL: https://mira-api.openjobs-ai.com

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 50+ 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, "message": "ok", "data": { ... } }

Note

Error responses use the same format with non-200 codes and "data": null. For example: { "code": 401, "message": "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.

Search Candidates

POST/v1/people-fast-search

Structured field search that bypasses AI parsing for faster results. At least one filter field is required. Returns up to 20 results.

Request Parameters

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

Basic Info

Parameter	Type	Description
full_name	string (max 200)	Full name (fuzzy 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 (fuzzy 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–3)	Min degree level: 0=Other/Unclear, 1=Bachelor, 2=Master, 3=PhD
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
  }'

Response Example

json

{
  "code": 200,
  "message": "ok",
  "data": [
    {
      "linkedin_url": "https://www.linkedin.com/in/xxx",
      "full_name": "John Smith",
      "headline": "Backend Engineer | Python | AWS",
      "address": {
        "city": "Austin",
        "state": "Texas",
        "country": "United States",
        "full": "Austin, Texas, United States"
      },
      "skills": ["python", "aws", "docker", "postgresql", "kubernetes"],
      "is_working": true,
      "active_experience_title": "Senior Backend Engineer",
      "active_experience_management_level": "Senior",
      "total_experience_duration_months": 144
    }
  ]
}

Note

data is a direct array of candidate profiles, up to 20 results.

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

Lookup Profiles

POST/v1/people-lookup

Fetch full candidate profiles by LinkedIn URLs. Accepts 1 to 50 URLs per request. URLs are automatically deduplicated and trailing slashes are stripped.

Request Parameters

Parameter	Type	Required	Description
linkedin_urls	string[] (1–50 items)	Yes	List of LinkedIn profile URLs to fetch

bash

curl -X POST "https://mira-api.openjobs-ai.com/v1/people-lookup" \
  -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,
  "message": "ok",
  "data": {
    "total": 2,
    "found": 1,
    "not_found": ["https://www.linkedin.com/in/yyy"],
    "results": [
      {
        "linkedin_url": "https://www.linkedin.com/in/xxx",
        "full_name": "Jane Doe",
        "headline": "Senior Python Engineer | Backend | Cloud",
        "profile_img": "https://media.licdn.com/dms/image/...",
        "address": {
          "city": "San Francisco",
          "state": "California",
          "country": "United States",
          "full": "San Francisco, California, United States"
        },
        "age": 35,
        "skills": ["python", "fastapi", "postgresql", "docker", "aws"],
        "is_working": true,
        "active_experience_title": "Senior Software Engineer",
        "active_experience_management_level": "Senior",
        "is_decision_maker": false,
        "total_experience_duration_months": 120,
        "experience": [
          {
            "is_current": true,
            "title": "Senior Software Engineer",
            "company_name": "Acme Corp",
            "company_type": "Privately Held",
            "industry": "Software Development",
            "start_time": "2021-03-01",
            "duration_months": 36
          }
        ],
        "education": [
          {
            "degree": "Bachelor of Science, Computer Science",
            "institution_name": "State University",
            "major": "Computer Science",
            "degree_level": 6
          }
        ]
      }
    ]
  }
}

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,
  "message": "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. 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, age)
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"],
    "histogram_fields": [{"field": "age", "interval": 10}]
  }'

Response Example

json

{
  "code": 200,
  "message": "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
      },
      "age_histogram": [
        { "key": 20, "count": 45   },
        { "key": 30, "count": 1820 },
        { "key": 40, "count": 2100 }
      ]
    }
  }
}

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,
  "message": "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,
  "message": "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 1 quota point. 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 1 quota point.

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,
  "message": "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. At least one filter field is required. Returns up to 20 results. Only active, non-deleted jobs are returned.

Request Parameters

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

Parameter	Type	Description
title	string (max 200)	Job title (fuzzy match)
description	string (max 500)	Job description keywords (fuzzy match)
company_name	string (max 200)	Company name (fuzzy 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"
  }'

Response Example

json

{
  "code": 200,
  "message": "ok",
  "data": [
    {
      "title": "Senior Python Engineer",
      "description": "We are looking for an experienced Python engineer...",
      "company_name": "Acme Corp",
      "seniority": "Mid-Senior level",
      "employment_type": "Full-time",
      "location": "San Francisco, California, United States",
      "country": "United States",
      "industry": "Technology, Information and Media",
      "function": "Engineering",
      "time_posted": "2025-06-15T00:00:00Z",
      "application_active": 1
    }
  ]
}

Note

data is a direct array of job records, up to 20 results.

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 20 results. 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 (fuzzy match)
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
  }'

Response Example

json

{
  "code": 200,
  "message": "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 20 results.

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

OpenJobs CLI

AI-powered talent intelligence from the command line. Search candidates, jobs, and scholars. Grade resumes. Compare profiles. Unlock contacts. Built on the Mira API.

@openjobs-ai/cli

npmjs.com/package/@openjobs-ai/cli

View on npm

Installation

Global install

bash

npm install -g @openjobs-ai/cli

Or run directly with npx

bash

npx @openjobs-ai/cli search people --skills Python

Note

The installed binary name is openjobs.

Setup

Get your API key from the , then configure it using one of the following methods:

bash

# Option 1: Environment variable (recommended)
export MIRA_KEY=mira_your_api_key

# Option 2: .env file in your project
echo "MIRA_KEY=mira_your_api_key" > .env

# Option 3: Pass directly per command
openjobs search people --skills Python --api-key mira_your_api_key

Commands

Command	Description
search people	Search for candidates with 30+ filters
search jobs	Search for job positions
search scholars	Search for academic scholars
lookup	Look up full LinkedIn profiles (1–50)
grade	Grade a resume against a job description
grade bulk	Bulk grade candidates (up to 20)
compare	Compare candidates side by side (2–10)
stats	Talent pool analytics and aggregations
unlock	Unlock contact information (consumes quota)
config	Manage CLI configuration

Usage Examples

Search Candidates

bash

openjobs search people --skills Python,AWS --country "United States"

openjobs search people \
  --title "Senior Engineer" \
  --company Google \
  --min-exp 60 \
  --city "San Francisco"

Search Jobs

bash

openjobs search jobs --title "Python Engineer" --country "United States" --type Full-time

Search Scholars

bash

openjobs search scholars --areas "Machine Learning","NLP" --h-index-min 20

Look Up Profiles

bash

openjobs lookup https://linkedin.com/in/janedoe

# Multiple profiles
openjobs lookup https://linkedin.com/in/janedoe https://linkedin.com/in/johnsmith

# From file
openjobs lookup --file urls.txt

Grade Resume vs Job Description

bash

openjobs grade \
  --cv "10 years Python backend, AWS certified" \
  --jd "Senior Python engineer with cloud experience"

# From files
openjobs grade --cv-file resume.txt --jd-file job.txt

Bulk Grade

bash

openjobs grade bulk \
  https://linkedin.com/in/alice \
  https://linkedin.com/in/bob \
  --jd-file job.txt

Compare Candidates

bash

openjobs compare \
  https://linkedin.com/in/alice \
  https://linkedin.com/in/bob \
  https://linkedin.com/in/carol

Talent Analytics

bash

openjobs stats --country "United States" --skills Python --group-by management_level

Unlock Contacts

bash

# Prompts for confirmation (consumes quota)
openjobs unlock https://linkedin.com/in/janedoe

# Skip confirmation
openjobs unlock https://linkedin.com/in/janedoe --yes

Result References (@N)

Search results are automatically numbered. Use @N to reference them in subsequent commands — no copy-pasting URLs needed.

bash

openjobs search people --skills Rust --country Germany
# Results: @1 through @20

openjobs lookup @1 @5
openjobs grade bulk @1 @2 @3 --jd-file job.txt
openjobs compare @1 @3
openjobs unlock @1 --yes

Output Formats

bash

# Auto-detect: terminal → table, pipe → JSON
openjobs search people --skills Python
openjobs search people --skills Python | jq '.[0]'

# Explicit format
openjobs search people --skills Python --format json
openjobs search people --skills Python --format csv
openjobs search people --skills Python --format table

# Write to file
openjobs search people --skills Python --output results.csv

# Select fields
openjobs search people --skills Python --fields full_name,skills,address

# Quiet mode
openjobs search people --skills Python --quiet --format json

Configuration

bash

openjobs config list               # Show all settings
openjobs config set default_format json
openjobs config get default_format
openjobs config reset              # Reset to defaults

Settings are stored in ~/.openjobs/config.json.

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-dev-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, age, exp_duration, gpa, institution_ranking, company_employees_count

Available `histogram_fields`

Field	Default Interval
experience_months	12
age	5
institution_ranking	50

Error Codes

All error responses use the unified format: { "code": 4xx/5xx, "message": "<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
422	422	Invalid parameter format or value
429	429	Rate limit exceeded (RPM)
500	500	Internal server error

Mira API Documentation

Overview

Quick Start: Agent-Skills

Available Skills

Installation

Authentication

Quick Start: Direct API Call

Authentication

Search Candidates

Request Parameters

Response Example

Lookup Profiles

Request Parameters

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

Search Scholars

Request Parameters

Response Example

OpenJobs CLI

Installation

Setup

Commands

Usage Examples

Result References (@N)

Output Formats

Configuration

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

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`