Grammarly Hello World

Overview

Score a text document using Grammarly's Writing Score API. Returns an overall score plus sub-scores for engagement, correctness, tone, and clarity.

Prerequisites

• Completed grammarly-install-auth setup
• Valid access token with scores-api:read scope

Instructions

Step 1: Score a Document

// hello-grammarly.ts
import 'dotenv/config';

const TOKEN = process.env.GRAMMARLY_ACCESS_TOKEN!;

async function scoreText(text: string) {
  const response = await fetch('https://api.grammarly.com/ecosystem/api/v2/scores', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ text }),
  });

  const result = await response.json();
  console.log('Overall Score:', result.overallScore);
  console.log('Engagement:', result.engagement);
  console.log('Correctness:', result.correctness);
  console.log('Clarity:', result.clarity);
  console.log('Tone:', result.tone);
  return result;
}

scoreText('Their going to the store tommorow to buy there supplys for the trip.').catch(console.error);

Step 2: AI Detection

async function detectAI(text: string) {
  const response = await fetch('https://api.grammarly.com/ecosystem/api/v1/ai-detection', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ text }),
  });
  const result = await response.json();
  console.log('AI Score:', result.score); // 0-100, higher = more likely AI
  return result;
}

Step 3: Plagiarism Detection

async function checkPlagiarism(text: string) {
  // Step 1: Create score request
  const createRes = await fetch('https://api.grammarly.com/ecosystem/api/v1/plagiarism', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${TOKEN}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ text }),
  });
  const { id } = await createRes.json();

  // Step 2: Poll for results
  let result;
  do {
    await new Promise(r => setTimeout(r, 3000));
    const statusRes = await fetch(`https://api.grammarly.com/ecosystem/api/v1/plagiarism/${id}`, {
      headers: { 'Authorization': `Bearer ${TOKEN}` },
    });
    result = await statusRes.json();
  } while (result.status === 'pending');

  console.log('Plagiarism score:', result.score);
  console.log('Matches:', result.matches?.length || 0);
  return result;
}

Step 4: curl Quick Test

curl -X POST https://api.grammarly.com/ecosystem/api/v2/scores \
  -H "Authorization: Bearer $GRAMMARLY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "This is a test sentence."}' | python3 -m json.tool

Output

• Writing score with engagement, correctness, clarity, and tone breakdown
• AI detection score (0-100)
• Plagiarism detection with source matches

Error Handling

Examples

Use a fictional sentence such as The sample system work correctly. in a sandbox request, verify the response shape without persisting its suggestions, then record fixture=grammar-basic-v1; request=accepted; retention=none; cleanup=complete.

Resources

• Writing Score API
• AI Detection API
• Plagiarism Detection API

Next Steps

Proceed to grammarly-local-dev-loop for development workflow.