API Reference Overview

The MIRI API provides RESTful endpoints for AI-powered resume-job matching analysis. All API endpoints follow consistent patterns for requests, responses, and error handling.

Base URL

https://open-miri-api.axistant.org/public/v1

Available APIs

Core APIs

API	Description	Use Case
Analysis API	Single resume-job matching analysis	Real-time analysis for individual candidates
Batch API	Process multiple analyses simultaneously	Bulk processing for recruitment campaigns

Management APIs

API	Description	Use Case
Webhook Integration	Verify signatures and handle retries	Receive real-time notifications

Monitoring APIs

API	Description	Use Case
Health Check	Service health status	Monitoring and alerting

Request Format

Headers

All requests must include these headers:

Miri-Api-Key: miri_live_sk_xxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
Accept: application/json

Request Body

Request bodies are JSON. A minimal analysis request looks like this:

{
  "resumeData": {
    "type": "pdf",
    "content": "base64-encoded PDF"
  },
  "jobPostingData": {
    "type": "html",
    "content": "<h1>Senior Backend Engineer</h1><p>Design scalable services...</p>"
  },
  "options": {
    "webhook": {
      "url": "https://partner.example.com/webhooks/analysis",
      "secret": "your-hmac-secret"
    }
  }
}

Content encoding

text/html payloads use UTF-8. pdf/docx payloads must be base64-encoded before sending.

Response Format

Success Response

Responses include a status boolean, the domain payload in data, and optional message/metadata fields:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "links": {
      "self": "/public/v1/analyses/550e8400-e29b-41d4-a716-446655440000"
    }
  },
  "message": null,
  "code": "SUCCESS",
  "metadata": null
}

Error Response

Error responses follow a consistent format with optional metadata:

{
  "success": false,
  "data": null,
  "message": "The request body is invalid",
  "code": "VAL001",
  "metadata": {
    "field": "resumeData.content",
    "error": "Required field is missing"
  }
}

Error Codes

Code	Message	HTTP Status
INVALID_API_KEY	Invalid or missing Miri-Api-Key header	401
AUTH001	Invalid API key	401
AUTH003	API key is suspended	403
VAL001	Invalid request format	400
VAL002	Missing required field	400
VAL003	Invalid field value	400
VAL004	Request size exceeds limit	400
BUS002	Insufficient credits	402
SVC001	Service temporarily unavailable	503
SVC002	Circuit breaker is open	503
SVC003	Dependency timeout	503
INT001	Internal server error	500
INTERNAL_ERROR	Internal error raised by API key filter	500
NOT001	Analysis not found	404
NOT003	Customer not found	404
NOT000	Resource not found	404

The metadata field is populated selectively:

• Validation errors (VAL001-VAL003): Includes the offending field, the invalid value, and when applicable validValues.
• Insufficient credits (BUS002): Adds required, available, and a purchaseUrl hint for buying credits.
• Service errors (SVC001-SVC003): Supply retryAfter in both headers and metadata; circuit-breaker responses also include service.
• Unexpected errors (INT001): Echo the supplied X-Request-ID to aid support investigations.
• Authentication failures: Filter-level rejections return INVALID_API_KEY (or INTERNAL_ERROR if the filter itself fails) without metadata; controller-level failures surface as AUTH001.

Data & Time Formats

• Dates: ISO-8601 strings (e.g., 2025-08-30T10:00:00Z)
• Webhook headers vs body timestamps may differ by design (see Webhooks API)

Edge throttling: An upstream traffic guard enforces 2,500 requests per 5-minute window per IP. When the limit is exceeded the guard returns 403 Forbidden with a minimal body and no additional rate-limit headers.

HTTP Status Codes

Status Code	Description
200 OK	Request successful
201 Created	Resource created successfully
202 Accepted	Request accepted for processing
204 No Content	Request successful, no content to return
400 Bad Request	Invalid request format or parameters
401 Unauthorized	Invalid or missing API key
402 Payment Required	Insufficient credits
403 Forbidden	Access denied (includes edge rate-limit responses)
404 Not Found	Resource not found
500 Internal Server Error	Server error
503 Service Unavailable	Service temporarily unavailable

Data Types

Content Types

Supported document format:

• text - Plain text content

Status Values

Analysis Status

• QUEUED - Analysis is waiting to be processed
• PROCESSING - Analysis is being processed
• COMPLETED - Analysis completed successfully
• FAILED - Analysis failed

Batch Status

• QUEUED - Batch is waiting to start
• PROCESSING - Batch is being processed
• COMPLETED - All items processed successfully
• PARTIAL - Some items succeeded, some failed
• FAILED - Batch processing failed

Pagination

Some list endpoints support pagination using query parameters:

• GET /public/v1/webhooks/{webhookId}/logs?page=0&size=20

Parameters

Parameter	Type	Default	Description
page	integer	0	Page number (0-indexed)
size	integer	20	Items per page (max: 100)
sort	string	createdAt,desc	Sort field and direction (where supported)

Response (example)

{
  "content": [...],
  "page": {
    "size": 20,
    "number": 0,
    "totalElements": 150,
    "totalPages": 8,
    "first": true,
    "last": false,
    "empty": false
  }
}

Rate Limiting

Edge throttling is enforced before requests reach the application: 2,500 requests per 5-minute window per source IP. When the threshold is exceeded the guard returns 403 Forbidden with a minimal body—no rate-limit headers are emitted. Monitor call volume through the usage dashboard (or your own telemetry) and implement client-side queues or backoff for bursty workloads.

Idempotency

For POST requests that create resources, you can ensure idempotency by including an idempotency key:

X-Idempotency-Key: unique-request-id-123

The same response will be returned for duplicate requests with the same idempotency key within 24 hours.

CORS Support

Browser traffic is accepted only from origins on the platform allow list. The default list covers the MIRI Console domains and localhost for development. Contact support if you need to register an additional production origin.

When a whitelisted site issues a request, the response headers include:

Access-Control-Allow-Origin: https://your-registered-origin.com
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: *
Access-Control-Expose-Headers: Authorization, X-New-Access-Token, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Access-Control-Allow-Credentials: true

Webhooks

Configure webhooks to receive real-time notifications:

1. Register webhook endpoint
2. Verify webhook signature
3. Process webhook events

Deliveries are attempted up to three times per event with a fixed two-second gap. If all retries fail, update the destination and replay the original request to trigger a new notification. See Webhook Signature Verification for verification details.

Next Steps

• Analysis API - Create and retrieve analyses
• Batch API - Process multiple analyses
• Authentication - Set up API authentication
• Note: Depending on validation failure path (e.g., JSON parsing vs. field validation), the specific VAL00x code may vary between VAL001 (invalid request) and VAL003 (invalid field value).