Public-facing GraphQL API for MediScan AI.

Getting Started

Base URL

Production: https://the-api.mediscan.ai/api

All API requests should be made to the GraphQL endpoint using POST method.

Quick Start Guide

1. Generate an API Key - Only administrators can create API keys. In your MediScan AI account, click the top-left dropdown menu and navigate to API Management to generate a new API key

2. Make Your First Request - Include your API key in the Authorization header:

   Authorization: Bearer YOUR_API_KEY
   

3. Create a Case - Create a case, queue a DOCX export using the existing preset-selection behavior, and receive signed URLs for file upload. To choose a specific preset, see Preset-Aware Exports below:

   const response = await fetch('https://the-api.mediscan.ai/api', {
                     method: 'POST',
                     headers: {
                       'Authorization': 'Bearer YOUR_API_KEY',
                       'Content-Type': 'application/json'
                     },
                     body: JSON.stringify({
                      query: `
                        mutation CreateCase($fileNames: [String!]!) {
                          createCase(fileNames: $fileNames, exportConfigs: [{ exportType: docx }]) {
                             caseId
                             signedUrl
                             exportId
                           }
                         }
                       `,
                       variables: {
                         fileNames: ['medical-record.pdf', 'lab-results.pdf']
                       }
                     })
                   });
                   
                   const { data } = await response.json();
                   console.log('Case created:', data.createCase.caseId);
                   console.log('Signed URLs:', data.createCase.signedUrl);
                   

4. Upload Files - Upload your files to the signed URLs (one URL per file):

   // Get the file to upload
                   const file = document.getElementById('fileInput').files[0];
                   
                   // Use the signed URL from createCase response
                   const signedUrl = data.createCase.signedUrl[0];
                   
                   const uploadResponse = await fetch(signedUrl, {
                     method: 'PUT',
                     body: file,
                     headers: {
                       'Content-Type': file.type || 'application/octet-stream'
                     }
                   });
                   
                   if (uploadResponse.ok) {
                     console.log('File uploaded successfully');
                   }
                   

   Important: Use the signed URL exactly as provided - do not add any additional headers or authentication.

5. Check Processing Status - Monitor case processing progress:

   const response = await fetch('https://the-api.mediscan.ai/api', {
     method: 'POST',
     headers: {
       'Authorization': 'Bearer YOUR_API_KEY',
       'Content-Type': 'application/json'
     },
     body: JSON.stringify({
      query: `
        query GetCaseStatus($caseId: String!) {
          getCaseStatus(caseId: $caseId) {
             status
             filesCount
             processedCount
           }
         }
       `,
      variables: { caseId: data.createCase.caseId }
    })
     });
   

const { data } = await response.json(); console.log(`Status: ${data.getCaseStatus.status}`); console.log(`Processed: ${data.getCaseStatus.processedCount}/${data.getCaseStatus.filesCount}`);

                6. **Get Case Details** - Retrieve full case information including exports:
                ```javascript
                const response = await fetch('https://the-api.mediscan.ai/api', {
                  method: 'POST',
                  headers: {
                    'Authorization': 'Bearer YOUR_API_KEY',
                    'Content-Type': 'application/json'
                  },
                  body: JSON.stringify({
                   query: `
                     query GetCase($caseId: String!) {
                       getCase(caseId: $caseId) {
                         id
                         patientName
                         created
                         exports {
                           exportId
                           status
                         }
                       }
                     }
                   `,
                   variables: { caseId: data.createCase.caseId }
                 })
                  });
                  
                  const { data } = await response.json();
                  console.log(\`Patient: ${data.getCase.patientName}\`);
                  console.log(\`Exports: ${data.getCase.exports.length}\`);
                

7. Get Export by ID - Retrieve a specific export with download URLs:

   const response = await fetch('https://the-api.mediscan.ai/api', {
     method: 'POST',
     headers: {
       'Authorization': 'Bearer YOUR_API_KEY',
       'Content-Type': 'application/json'
     },
     body: JSON.stringify({
      query: `
        query GetExport($exportId: String!) {
          getExport(exportId: $exportId) {
            id
            files {
              signedUrl
              filename
              mimeType
            }
          }
        }
      `,
      variables: { exportId: data.createCase.exportId }
    })
     });
   

const { data } = await response.json(); data.getExport.files.forEach(file => { console.log(`${file.filename}: ${file.signedUrl}`); });

                8. **Get Case with Exports** - Retrieve full case details with all exports:
                ```javascript
                const response = await fetch('https://the-api.mediscan.ai/api', {
                  method: 'POST',
                  headers: {
                    'Authorization': 'Bearer YOUR_API_KEY',
                    'Content-Type': 'application/json'
                  },
                  body: JSON.stringify({
                   query: `
                     query GetCase($caseId: String!) {
                       getCase(caseId: $caseId) {
                         id
                         patientName
                         exports {
                           exportId
                           status
                           files {
                             signedUrl
                             filename
                           }
                         }
                       }
                     }
                   `,
                   variables: { caseId: data.createCase.caseId }
                 })
                  });
                  
                  const { data } = await response.json();
                  data.getCase.exports.forEach(exp => {
                 console.log(\`Export ${exp.exportId} (${exp.status}):\`);
                 exp.files.forEach(file => console.log(\`  ${file.filename}\`));
                });
                

9. Update Cases (Optional) - Add new files or modify case properties:

   const response = await fetch('https://the-api.mediscan.ai/api', {
                     method: 'POST',
                     headers: {
                       'Authorization': 'Bearer YOUR_API_KEY',
                       'Content-Type': 'application/json'
                     },
                     body: JSON.stringify({
                      query: `
                        mutation UpdateCase($caseId: String!, $fileNames: [String!]) {
                          updateCase(caseId: $caseId, fileNames: $fileNames) {
                             caseId
                             signedUrl
                             success
                             message
                           }
                         }
                       `,
                       variables: {
                         caseId: 'your-case-id',
                         fileNames: ['additional-document.pdf']
                       }
                     })
                   });
                   
                   const { data } = await response.json();
                   console.log('Case updated:', data.updateCase.success);
                   console.log('New signed URLs:', data.updateCase.signedUrl);
                   

Note: The examples above show basic usage with commonly used fields. Many more fields and options are available for each query and mutation. Please refer to the full API schema documentation below for complete details on all available fields, types, and configurations.

Preset-Aware Exports

Query getPresets with the same API key used for your case and export requests. It takes no team ID argument: results belong to the API key's team and exclude case-local presets.

query GetPresets {
  getPresets {
    id
    title
    usedBy {
      id
      name
      email
    }
  }
}

usedBy lists users who selected that preset as their default for this team, not users who previously exported with it. It is empty when no team users have selected it.

Create a case and export with a selected preset

1. Choose an id from getPresets.
2. Call createCase without exportConfigs, upload PDFs using the returned signed URLs, and wait for processing to complete. Omitting exportConfigs avoids creating an additional automatic export.
3. Call createExport with the case ID and selected preset ID:

mutation CreateExport($caseId: String!, $presetId: String!) {
  createExport(
    caseId: $caseId
    config: { exportType: docx, presetOverride: $presetId }
  ) {
    exportId
    status
  }
}

Example GraphQL variables:

{ "caseId": "your-case-id", "presetId": "id-returned-by-getPresets" }

4. Poll getExport(exportId: ...) using the exportId returned by createExport. While pending, it reports no downloadable files in the GraphQL errors array. Once ready, download each file from its signedUrl. This ID is the public request ID, not an internal export-record ID.

Selection rules and other export entry points

• presetOverride is optional in createExport.config and in each item of createCase.exportConfigs or updateCase.exportConfigs. Existing requests do not need to change or call getPresets.
• With createCase.exportConfigs, exports are queued and the returned exportId identifies the batch. updateCase does not return an export ID; use a separate createExport call when you need an ID to poll. When adding files, finish uploading and processing them before requesting an export separately.
• Omit presetOverride or pass null to preserve the previous selection: use the case's preset for the API user when present, otherwise that user's default preset. Existing AccidentMate preset assignment and selection are unchanged when no override is supplied.
• Default lookup and export ownership currently use the API user's current team. Keep it aligned with the API key's team; an explicit override does not change export ownership.
• The override applies only to the requested export; it does not change user defaults or case presets. Preset settings are saved when the export is requested.
• Explicit grouping and sorting override the preset's corresponding settings. Without them, the selected preset supplies those settings when available.
• Missing, foreign-team, and case-local override IDs are rejected before quota consumption or case changes. Check the GraphQL errors array; production may mask the detailed validation message.

Error Handling

The API uses standard GraphQL error responses. All errors are returned in the errors array of the response.

Common Error Codes

Code	Status	Description
UNAUTHENTICATED	401	Invalid or missing API key
FORBIDDEN	403	Insufficient permissions to access resource
BAD_USER_INPUT	400	Invalid input parameters
NOT_FOUND	404	Requested resource not found
INTERNAL_SERVER_ERROR	500	Server error occurred
RATE_LIMIT_EXCEEDED	429	Too many requests

Rate Limiting

To ensure fair usage and system stability, API requests are rate limited.

Limits:

• 100 requests per minute per API key
• 1,000 requests per hour per API key

When rate limited, you'll receive a 429 Too Many Requests error. Wait until the reset time before making additional requests.

Best Practices:

• Implement exponential backoff for retries
• Cache responses when appropriate
• Batch operations when possible

https://the-api.mediscan.ai/api