grammarly-hello-world

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

```typescript
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

Error	Cause	Solution
`401 Unauthorized`	Token expired	Re-authenticate
`400 Bad Request`	Text too short (< 30 words)	Minimum 30 words required
`413 Payload Too Large`	Text > 100,000 characters	Split into chunks
`429 Rate Limited`	Too many requests	Implement backoff

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

Next Steps

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