Developer API

MySimpleReport API Integration Guide

Submit medical files or text, receive structured analysis, and build plain-language health report workflows into your own product.

Quick start View endpoints
POST /v1/analyze-file
curl -X POST https://dev.mysimplereport.com/v1/analyze-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file_url": "https://example.com/report.pdf" }'
Version1.0.0
ProtocolHTTPS only
FormatJSON
AuthenticationBearer token
API

Build against MySimpleReport

The MySimpleReport API enables developers to programmatically submit files and text for intelligent analysis. The API returns structured analysis_results in JSON format, ready to integrate into your application workflow.

1. How Authentication Works

All API requests must be authenticated using an API key passed as a Bearer token in the Authorization header.

The Bearer Token Lifecycle

Every request must include your API Key inside the Authorization HTTP header using the standard Bearer scheme (defined in RFC 6750):

Authorization: Bearer YOUR_API_KEY

Behind the scenes: The server reads the header, strips out the Bearer prefix, and hashes your raw key utilizing secure SHA-256 algorithms. It checks its presence against the active database clusters, ensuring the key hasn't expired or crossed rate thresholds before granting request processing rights.

Security Notice: Never expose your API key in client-side code, public repositories, URL query parameters, request bodies, or logs. Store it securely using environment variables or a secrets manager over secure HTTPS.

Required Request Headers

Header Value Required Notes
Authorization Bearer YOUR_API_KEY Yes Prefix must be exactly Bearer (including the trailing space)
Content-Type application/json Yes All inbound request bodies must be JSON format
Accept application/json Yes All outbound responses are served in JSON format

Example Raw Header Block

POST /v1/analyze-file HTTP/1.1
Host: dev.mysimplereport.com
Authorization: Bearer msr_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4
Content-Type: application/json
Accept: application/json

2. Base Configuration

Base URL https://dev.mysimplereport.com/v1
Protocol HTTPS (TLS 1.2+ required)
Data Format JSON (Request body & Response parsing)
Auth Method Bearer Token (API Key Verified)
Encoding UTF-8

3. API Endpoints

3.1 Analyze Single File

Submits a single file for analysis via a publicly accessible URL.

POST /analyze-file

Request Body Fields

Parameter Type Required Description
file_url String Yes A publicly accessible URL pointing to the file to analyze
purpose String No Optional context hint (e.g., "invoice", "contract", "report")

cURL Example

curl -X POST https://dev.mysimplereport.com/v1/analyze-file \
  -H "Authorization: Bearer msr_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "file_url": "https://yourdomain.com/files/report.pdf",
    "purpose": "financial_report"
  }'

Expected Response (200 OK)

{
  "status": "success",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "file_url": "https://yourdomain.com/files/report.pdf",
  "filename": "report.pdf",
  "file_type": "application/pdf",
  "size_bytes": 204800,
  "submitted_at": "2026-06-19T10:32:00Z",
  "processed_at": "2026-06-19T10:32:04Z",
  "analysis_results": {
    "summary": "Q2 financial report covering revenue and expenditure.",
    "language": "en",
    "page_count": 12,
    "key_topics": ["revenue", "quarterly_growth", "operating_costs"],
    "sentiment": "neutral",
    "confidence_score": 0.97,
    "extracted_data": {
      "dates_mentioned": ["2026-04-01", "2026-06-30"],
      "entities": ["Acme Corp", "John Smith"],
      "custom_tags": ["finance", "q2"]
    }
  },
  "usage": {
    "documents_analyzed": 1,
    "credits_used": 1,
    "credits_remaining": 499
  }
}

3.2 Analyze Multiple Files

Submits two or more files in a single request for batch analysis (maximum of 20 elements per batch array request).

POST /analyze-multiple-files

Supported Formats Matrix

Category Formats Extension Mapping
Documents .pdf
Images .jpg, .jpeg, .png, .gif, .webp, .tiff, .bmp

cURL Example

curl -X POST https://dev.mysimplereport.com/v1/analyze-multiple-files \
  -H "Authorization: Bearer msr_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "file_urls": [
      "https://yourdomain.com/files/contract.docx",
      "https://yourdomain.com/files/invoice.pdf",
      "https://yourdomain.com/files/photo.jpg"
    ],
    "purpose": "legal_review"
  }'

Expected Response (200 OK)

{
  "status": "success",
  "request_id": "z9y8x7w6-v5u4-t3s2-r1q0-p9o8n7m6l5k4",
  "submitted_at": "2026-06-19T11:00:00Z",
  "processed_at": "2026-06-19T11:00:09Z",
  "total_files": 3,
  "results": [
    {
      "file_url": "https://yourdomain.com/files/contract.docx",
      "filename": "contract.docx",
      "file_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "size_bytes": 51200,
      "analysis_results": {
        "summary": "Service agreement between Acme Corp and Beta Ltd.",
        "language": "en",
        "key_topics": ["service_terms", "liability", "termination_clause"],
        "sentiment": "formal",
        "confidence_score": 0.95
      }
    },
    {
      "file_url": "https://yourdomain.com/files/invoice.pdf",
      "filename": "invoice.pdf",
      "file_type": "application/pdf",
      "size_bytes": 30720,
      "analysis_results": {
        "summary": "Invoice #INV-2026-0042 for consulting services.",
        "language": "en",
        "key_topics": ["billing", "consulting", "payment_due"],
        "sentiment": "neutral",
        "confidence_score": 0.99
      }
    },
    {
      "file_url": "https://yourdomain.com/files/photo.jpg",
      "filename": "photo.jpg",
      "file_type": "image/jpeg",
      "size_bytes": 102400,
      "analysis_results": {
        "summary": "Image of a signed document with visible text.",
        "detected_text": "Signed on June 15, 2026 by J. Smith",
        "objects_detected": ["document", "signature"],
        "confidence_score": 0.91
      }
    }
  ],
  "usage": {
    "documents_analyzed": 3,
    "credits_used": 3,
    "credits_remaining": 497
  }
}

3.3 Analyze Text

Submits raw text content directly for processing. No file host requirement is needed (max limit of 100,000 characters).

POST /analyze-text

cURL Example

curl -X POST https://dev.mysimplereport.com/v1/analyze-text \
  -H "Authorization: Bearer msr_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "text": "Q2 2026 earnings show 15% net revenue growth driven by enterprise segment.",
    "language": "en",
    "purpose": "financial_summary"
  }'

Expected Response (200 OK)

{
  "status": "success",
  "request_id": "t3s2r1q0-p9o8-n7m6-l5k4-j3i2h1g0f9e8",
  "submitted_at": "2026-06-19T12:00:00Z",
  "processed_at": "2026-06-19T12:00:02Z",
  "char_count": 74,
  "word_count": 13,
  "analysis_results": {
    "summary": "Q2 2026 shows 15% net revenue growth in enterprise.",
    "language": "en",
    "key_topics": ["earnings", "quarterly_growth", "enterprise", "revenue"],
    "sentiment": "positive",
    "confidence_score": 0.98,
    "extracted_data": {
      "dates_mentioned": ["Q2 2026"],
      "numeric_values": ["15%"],
      "entities": []
    }
  },
  "usage": {
    "documents_analyzed": 1,
    "credits_used": 1,
    "credits_remaining": 496
  }
}

4. Request Parameters Reference

Parameter Name Target Endpoint(s) Type Specification Required Status Functional Description
file_url analyze-file String Yes URL route pointing to a single file object layout
file_urls analyze-multiple-files String[] (Array) Yes Array structure storing file URLs (maximum capacity size: 20)
text analyze-text String Yes Raw body content strings intended for validation parsing
purpose All Endpoints String No Context hint parameter targeting processing accuracy bounds
language analyze-text String No Language explicit indicator tracking standard ISO 639-1 layout formats

5. Status & Error Reference

All structured responses that fail processing return consistent error objects. Click an entry in the list down below to inspect detailed schema implementations:

HTTP Status Error Payload Code Root Core Cause Condition
400 Bad Request BAD_REQUEST Malformed payload JSON strings or absent mandatory parameters.
401 Unauthorized UNAUTHORIZED Missing credentials or invalid bearer token configurations.
401 Unauthorized KEY_EXPIRED The allocated API key has passed its preconfigured retention lifespan.
403 Forbidden KEY_DISABLED Key execution parameters suspended via developer administration consoles.
402 Payment Required QUOTA_EXPIRED Subscription tiers or assigned runtime quotas have reached end-of-life status.
422 Unprocessable Entity VALIDATION_ERROR Unreachable source URL, corrupted files, or unsupported type schemas.
429 Too Many Requests RATE_LIMIT_EXCEEDED_DAILY The workspace has depleted its rolling daily request count limit constraints.
429 Too Many Requests RATE_LIMIT_EXCEEDED_MONTHLY Monthly processing transaction quotas have been completely filled out.
429 Too Many Requests SPEND_LIMIT_EXCEEDED Financial safety limits or billing cap milestones were reached.
500 Internal Error INTERNAL_SERVER_ERROR Unexpected system state exceptions in backend server engine pools. 
// Select a row from the validation matrix above to load contextual response payload schemas...

6. Production Integration Checklist

Ensure all system constraints match these targets prior to executing updates inside live production runtime architectures:

  • Generate the API keys strictly inside official developer administration dashboards.
  • Bind API credentials inside environment variables (e.g., MYSIMPLEREPORT_API_KEY) to decouple from repository scopes.
  • Verify header blocks supply accurate spacing configurations: Authorization: Bearer {key}.
  • Mandate explicit setting for Content-Type: application/json and Accept: application/json flags on client engines.
  • Implement upstream file URL access checks to confirm data pipelines can resolve external downloads seamlessly.
  • Run validation filters over targeted file extensions against support matrices before initiating payload requests.
  • Capture, map, and output unique request_id logs to localized database engines to assist trace investigations.
  • Write catch handlers inside application clients to intercept 401 states and trigger check mechanisms.
  • Build automated exponential retry routines leveraging the resets_at timestamps to systematically step around 429 throttling limits.
  • Set up alerting notification thresholds monitored against the credits_remaining tracking variables.