API Reference

Complete reference for the MIMS REST API, including authentication, endpoints, and response formats.

API Overview

The MIMS API is organized around REST principles. It accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

REST API

Core REST API endpoints for documents, organizations, and API keys.

SDK Endpoints

Endpoints specifically designed for SDK integration.

Types Reference

Complete TypeScript type definitions for the SDK.

Base URL

Production: https://api.mims-tech.com
Development: https://api-dev.mims-tech.com

Authentication

All API requests require authentication using an API key. Include your API key in the X-API-Key header:

cURL Examplebash

curl -X GET https://api.mims-tech.com/sdk/documents/doc_123 \
  -H "X-API-Key: pk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json"

API Key Types

pk_* - Public keys for client-side SDK usage
sk_* - Secret keys for server-side operations only

Response Format

All responses follow a consistent JSON structure:

Success Responsejson

{
  "success": true,
  "data": {
    // Response data here
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Error Responsejson

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid document ID format",
    "details": {
      "field": "documentId",
      "reason": "Must be a valid UUID"
    }
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

HTTP Status Codes

Code	Description
`200`	Success - Request completed successfully
`201`	Created - Resource created successfully
`400`	Bad Request - Invalid request body or parameters
`401`	Unauthorized - Missing or invalid API key
`403`	Forbidden - API key lacks required permissions
`404`	Not Found - Resource doesn't exist
`422`	Unprocessable Entity - Validation failed
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Server-side error

Rate Limiting

API requests are rate limited based on your plan. Rate limit information is included in response headers:

Rate Limit Headerstext

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705312200

Rate Limit Exceeded

When you exceed the rate limit, you'll receive a 429 response. Implement exponential backoff in your retry logic.

Pagination

List endpoints support cursor-based pagination:

Paginated Responsejson

{
  "success": true,
  "data": [...],
  "pagination": {
    "cursor": "eyJpZCI6MTIzfQ==",
    "hasMore": true,
    "limit": 20
  }
}

Pagination Requestbash

# First page
curl "https://api.mims-tech.com/documents?limit=20"

# Next page
curl "https://api.mims-tech.com/documents?limit=20&cursor=eyJpZCI6MTIzfQ=="

Error Codes

Code	Description
`INVALID_API_KEY`	The API key is malformed or doesn't exist
`EXPIRED_API_KEY`	The API key has expired
`INSUFFICIENT_PERMISSIONS`	The API key lacks required scopes
`VALIDATION_ERROR`	Request body validation failed
`DOCUMENT_NOT_FOUND`	The requested document doesn't exist
`SUBMISSION_FAILED`	Document submission processing failed
`RATE_LIMIT_EXCEEDED`	Too many requests in time window

SDK vs Direct API

You can use the API directly or through the SDK. The SDK provides:

Automatic authentication header injection
Request timeout handling
Type-safe responses with TypeScript
Built-in retry logic for transient failures

SDK vs Directtsx

// Using SDK (recommended)
const { apiRequest } = useSDK();
const document = await apiRequest<Document>('/sdk/documents/doc_123');

// Direct fetch (manual authentication)
const response = await fetch('https://api.mims-tech.com/sdk/documents/doc_123', {
  headers: {
    'X-API-Key': 'pk_live_xxx',
    'Content-Type': 'application/json',
  },
});
const document = await response.json();