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.

Grade Candidates

AI-powered CV matching and scoring

Search & Filter

Structured candidate search with 50+ filters

Profile Lookup

Full profiles by LinkedIn URL

Analytics

Aggregate talent pool statistics

Quick Start

Make your first API call in seconds. Replace YOUR_API_KEY with the key from your API Keys page.

bash

curl -X POST "https://mira-api.openjobs-ai.com/v1/people-grade" \
  -H "Authorization: Bearer YOUR_API_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.

Authentication

Include your API key as a Bearer token in the Authorization header of every request:

bash

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

Tip

You can manage your API keys from the API Keys page in the dashboard.

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	Yes	Candidate resume text (max 5000 chars)
jd	string	Yes	Job description text (max 5000 chars)

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 match with relevant experience..."
    }
  }
}

Search Candidates

POST/v1/people-fast-search

Filter candidates by structured fields. Bypasses AI parsing for faster results. At least one filter field is required. Returns up to 20 results.

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
  }'

Note

See the reference for all available filter fields.

Analytics

POST/v1/people-stats

Get aggregate analytics on the candidate pool. Supports group-by counts, numeric statistics (min/max/avg), and histogram bucketing.

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}]
  }'

Lookup Profiles

POST/v1/people-lookup

Fetch full candidate profiles by LinkedIn URL. Accepts 1 to 50 URLs per request.

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_xxxxxxxxxxxx" \
  -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 YOUR_API_KEY"

Error Codes

HTTP Status	Description
400	Invalid or missing request parameters
401	Missing/invalid Authorization header
402	Quota exhausted
403	API key disabled or insufficient scope
429	Rate limit exceeded
500	Internal server error