Analysis API

Submit individual resume–job pairs for premium analysis results. Responses are asynchronous: the acceptance payload contains an ID you can poll or attach to webhooks.

Authentication

Miri-Api-Key: miri_live_sk_xxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

All Analysis API requests require a valid MIRI API key. Optionally include an X-Request-ID header to enable idempotent retries.

Create Analysis

Create a new analysis for a single resume and job posting.

Endpoint

POST /public/v1/analyses

Headers

Miri-Api-Key: miri_live_sk_xxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
X-Request-ID: 6dc2d2d2-5a72-4b47-9f9c-8f6aa2a9244e (optional)

Request Body

Content encoding

text/html payloads must use UTF-8 text. pdf/docx payloads must be base64-encoded. Requests larger than 10 MB are rejected.

{
  "resumeData": {
    "type": "pdf",
    "content": "UEsDBBQABgAIAAAAIQAAAAAAAAAAAAAAAAAJAAAAdXJsLnR4dFxTZW5pb3IgQmFja2VuZCBFbmdpbmVlciAtIFJlc3VtZSBFeGNlcnB0cy4uLg=="
  },
  "jobPostingData": {
    "type": "html",
    "content": "<h1>Senior Backend Engineer</h1><p>Design scalable services...</p>"
  },
  "options": {
    "webhook": {
      "url": "https://partner.example.com/hooks",
      "secret": "optional-hmac-secret"
    }
  }
}

Field Reference

Field	Type	Required	Description
`resumeData`	object	Yes	Resume payload.
`resumeData.type`	string	Yes	`text`, `html`, `pdf`, or `docx`.
`resumeData.content`	string	Yes	UTF-8 text/HTML, or base64-encoded binary when `type` is `pdf`/`docx` (10 MB request limit).
`jobPostingData`	object	Yes	Job description payload (same schema as `resumeData`).
`options`	object	No	Container for optional settings.
`options.webhook`	object	No	Completion webhook configuration.
`options.webhook.url`	string	Yes	HTTPS endpoint for delivery.
`options.webhook.secret`	string	No	Optional signing secret (32–64 ASCII characters recommended).

X-Request-ID (Idempotency)

Provide a unique string (max 255 ASCII characters, UUID v4 recommended) in X-Request-ID to make retries safe. Duplicate submissions with the same value reuse the original analysis, return the latest status (PROCESSING, COMPLETED, or FAILED), and never deduct extra credits.

Response (202 Accepted)

  "success": true,
  "data": {
    "id": "0199d5b8-3a2f-4f62-8f4d-9c4fdfb7c2a1",
    "status": "QUEUED",
    "estimatedTime": 30,
    "createdAt": "2025-09-19T10:15:23.456Z",
    "webhook": {
      "url": "https://partner.example.com/hooks",
      "delivery": {
        "state": "PENDING",
        "lastAttemptAt": null,
        "lastStatusCode": null,
        "attemptCount": 0,
        "lastError": null
      }
    },
    "links": {
      "self": "/public/v1/analyses/0199d5b8-3a2f-4f62-8f4d-9c4fdfb7c2a1"
    },
    "metadata": {
      "creditsUsed": 1
    }
  },
  "message": null,
  "code": "SUCCESS",
  "metadata": null
}

Response Fields

Field	Type	Description
`id`	string	Analysis identifier used for polling or retrieval.
`status`	string	Initial state, always `QUEUED`.
`estimatedTime`	integer	Estimated completion time in seconds (defaults to 30). Not recalculated after acceptance.
`webhook`	object/null	Echo of configured webhook plus delivery telemetry.
`links.self`	string	Canonical URL for the analysis resource.
`metadata.creditsUsed`	integer	Reserved credits (always `1` for live analyses). The field is omitted while processing or if the run fails (no credit deducted).

Retrieve Analysis

Fetch the current status or completed result.

Endpoint

GET /public/v1/analyses/{analysisId}

Path Parameters

Parameter	Type	Description
`analysisId`	string	ID returned by the create endpoint.

Response (200 OK)

  "success": true,
  "data": {
    "id": "0199f6ac-5c23-41b0-904b-6b9f7c5f2c11",
    "status": "COMPLETED",
    "createdAt": "2025-09-19T10:15:23.456Z",
    "completedAt": "2025-09-19T10:16:45.123Z",
    "processingTime": 82031,
    "estimatedTime": null,
    "result": {
      "analysis": { "experience": { "score": 0.82, "comments": { "applicant_perspective": "Tailor accomplishments to the posting." } } },
      "essential": { "skillAnalysisResults": [] },
      "preferred": { "skillAnalysisResults": [] },
      "interviewQuestions": [],
      "overallEvaluation": {
        "feedback": [],
        "recommendations": [],
        "improvementSuggestionsForApplicant": [],
        "resumeFeedback": [],
        "coverLetterFeedback": []
      }
    },
    "metadata": {
      "creditsUsed": 1
    },
    "webhook": {
      "url": "https://partner.example.com/hooks",
      "delivery": {
        "state": "SUCCESS",
        "lastAttemptAt": "2025-09-19T10:16:45.500Z",
        "lastStatusCode": 200,
        "attemptCount": 1,
        "lastError": null
      }
    },
    "links": {
      "self": "/public/v1/analyses/0199f6ac-5c23-41b0-904b-6b9f7c5f2c11"
    }
  },
  "message": null,
  "code": "SUCCESS",
  "metadata": null
}

Response Fields

Field	Type	Description
`status`	string	`QUEUED`, `PROCESSING`, `COMPLETED`, or `FAILED`.
`createdAt`	string	ISO 8601 timestamp when the analysis was accepted.
`completedAt`	string/null	Completion timestamp; `null` until finished.
`processingTime`	integer/null	Processing duration in milliseconds (set for terminal states).
`estimatedTime`	integer/null	Remaining seconds while pending. Omitted after completion or failure.
`result`	object/null	Present when `status` is `COMPLETED`; see the note below for structure.
`error`	object/null	Present when `status` is `FAILED`. Includes `code` and `message`.
`metadata.creditsUsed`	integer/null	Returned when the run has been accepted or completed. The field is omitted while processing or if the run ultimately fails (no credit deducted).
`webhook.delivery`	object/null	Delivery telemetry (`state`, `lastAttemptAt`, `lastStatusCode`, `attemptCount`, `lastError`).
`links.self`	string	Resource URL for subsequent polling.

Result structure

The result object includes section-level evaluations (analysis.*), skill recommendations (essential / preferred), generated interview guidance, and overallEvaluation feedback arrays.

Sandbox Test Run

Run end-to-end tests without consuming credits or invoking production models.

Create Sandbox Analysis

POST /public/v1/analyses/test-run

Same headers and request body as the production endpoint.
Responds immediately with canned metadata and metadata.creditsUsed = 0.
Sandbox IDs expire after 10 minutes; expired IDs return NOT001.

Retrieve Sandbox Snapshot

GET /public/v1/analyses/test-run/{analysisId}

Sandbox responses mirror the production schema but always contain deterministic sample results. Use them only for tests—sandbox IDs are rejected by GET /public/v1/analyses/{id}.

Webhook Events

When options.webhook is provided, the platform emits notifications during the lifecycle of an analysis:

analysis.completed — triggered after the result is persisted.
analysis.failed — triggered when processing reaches a terminal failure.

Each delivery wraps the payload in an envelope with the event name and an epoch timestamp (seconds):

  "event": "analysis.completed",
  "timestamp": 1758407305,
  "data": {
    "id": "0199f6ac-5c23-41b0-904b-6b9f7c5f2c11",
    "type": "analysis",
    "status": "COMPLETED"
  }
}

Failure notifications reuse the same structure and add an error field inside data. Each request includes the following headers:

X-Webhook-Event: event name (for example, analysis.completed).
X-Webhook-Timestamp: epoch milliseconds when the request was sent.
X-Webhook-Signature: HMAC-SHA256 signature when you supply webhook.secret.

Deliveries retry up to three times with a fixed two-second interval. The latest attempt is visible on polling responses via webhook.delivery (state, lastStatusCode, attemptCount, and lastError).

Error Codes

Code	HTTP Status	Description
`INVALID_API_KEY`	401	Missing or malformed `Miri-Api-Key` header.
`AUTH001`	401	Key could not be authenticated.
`AUTH003`	403	Key is suspended or revoked.
`VAL001`	400	Unsupported content type or JSON parsing failure.
`VAL002`	400	Required fields (`resumeData`, `jobPostingData`, or properties) missing.
`VAL003`	400	Field validation failed (invalid enum, malformed UUID, etc.).
`VAL004`	400	Payload exceeds size limits (base64 envelope capped at 10 MB).
`BUS002`	402	Insufficient credits. `metadata` includes `required`, `available`, and `purchaseUrl`.
`NOT001`	404	Analysis not found (live or sandbox).
`SVC001`	503	Temporary platform outage.
`SVC002`	503	Circuit breaker open after repeated downstream failures.
`SVC003`	503	Downstream timeout.
`INT001`	500	Unexpected server error.

Batch API – Submit multiple analyses in one request.
Payment API – Purchase credits before running analyses.

Authentication​

Create Analysis​

Endpoint​

Headers​

Request Body​

Field Reference​

Response (202 Accepted)​

Response Fields​

Retrieve Analysis​

Endpoint​

Path Parameters​

Response (200 OK)​

Response Fields​

Sandbox Test Run​

Create Sandbox Analysis​

Retrieve Sandbox Snapshot​

Webhook Events​

Error Codes​

Related Endpoints​

Authentication

Create Analysis

Endpoint

Headers

Request Body

Field Reference

Response (202 Accepted)

Response Fields

Retrieve Analysis

Endpoint

Path Parameters

Response (200 OK)

Response Fields

Sandbox Test Run

Create Sandbox Analysis

Retrieve Sandbox Snapshot

Webhook Events

Error Codes

Related Endpoints