API Documentation

PassTheNote provides a comprehensive REST API for practicing API automation testing. Use it with Postman, REST Assured, Axios, or any HTTP client to build API test suites.

Quick Start:

Base URL

https://www.passthenote.com/api/v1

All API endpoints are prefixed with /api/v1

Authentication

Most endpoints require authentication using JWT tokens. Include the token in the Authorization header.

POST /auth/login

Authenticate and receive a JWT token

Request Body:

{
  "email": "test@test.com",
  "password": "Test@1234"
}

Response (200 OK):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "1",
    "email": "test@test.com",
    "name": "Test User"
  }
}

Using the Token

Include the token in the Authorization header for protected endpoints:

Authorization: Bearer YOUR_JWT_TOKEN_HERE

Products

GET /products

List all products (public endpoint)

Response (200 OK):

[
  {
    "id": "1",
    "name": "Automation Testing Course",
    "price": 49.99,
    "description": "Complete Selenium course",
    "inStock": true
  }
]

GET /products/:id

Get a single product by ID

Response (200 OK):

{
  "id": "1",
  "name": "Automation Testing Course",
  "price": 49.99,
  "description": "Complete Selenium course with hands-on projects",
  "inStock": true,
  "category": "Education"
}

Orders

GET /orders

List all orders for authenticated user

🔒 Requires authentication

Response (200 OK):

[
  {
    "id": "order_123",
    "userId": "1",
    "items": [...],
    "total": 149.97,
    "status": "completed",
    "createdAt": "2025-12-05T10:30:00Z"
  }
]

POST /orders

Create a new order

🔒 Requires authentication

Request Body:

{
  "items": [
    {
      "productId": "1",
      "quantity": 2
    }
  ],
  "shippingAddress": {
    "street": "123 Test St",
    "city": "QA City",
    "zip": "12345"
  }
}

Notes

GET /notes

List all public notes

Query Parameters:

  • tag - Filter by tag (optional)
  • search - Search in title/content (optional)

Response (200 OK):

[
  {
    "id": "note_1",
    "title": "Selenium Best Practices",
    "content": "Use explicit waits...",
    "tags": ["selenium", "testing"],
    "author": "Test User",
    "createdAt": "2025-12-01T14:00:00Z"
  }
]

POST /notes

Create a new note

🔒 Requires authentication

Request Body:

{
  "title": "My Testing Notes",
  "content": "Key learnings from today...",
  "tags": ["learning", "automation"],
  "isPublic": true
}

OTP / Mock Inbox (Enterprise Simulation)

Enterprise-grade OTP testing with magic links, email delays, spam folder simulation, and polling strategies.

POST /otp/send

Generate OTP with enterprise features

Request Body:

{
  "email": "testuser@passthenote.com",
  "purpose": "login", // optional: login, signup, password-reset
  "triggerSpam": false // optional: true = email goes to SPAM folder
}

Query Parameters:

  • ?delay=true - Simulates 5-second email delivery delay

Response (200 OK):

{
  "message": "OTP sent successfully",
  "email": "testuser@passthenote.com",
  "expiresIn": "10 minutes",
  "folder": "INBOX", // or "SPAM" if triggerSpam=true
  "delayed": true
}

GET /otp/inbox/:email

Retrieve OTP with magic link support

⚠️ May return 202 if email is delayed - implement polling!

Response (200 OK):

{
  "email": "testuser@passthenote.com",
  "otp": "123456",
  "magicLink": "https://www.passthenote.com/auth/magic-login?token=abc...",
  "purpose": "login",
  "folder": "INBOX", // Check this! Could be "SPAM"
  "expiresIn": "574 seconds"
}

Response (202 Accepted) - Email Delayed:

{
  "message": "Email is being delivered",
  "waitTime": "3 seconds",
  "code": "EMAIL_DELAYED"
}

💡 Interview Question: How would you poll this endpoint until you get 200 OK?

POST /otp/verify

Verify OTP or magic link token

Request Body (Option 1: OTP):

{
  "email": "testuser@passthenote.com",
  "otp": "123456"
}

Request Body (Option 2: Magic Link):

{
  "email": "testuser@passthenote.com",
  "magicToken": "abc123..." // Extract from magicLink URL
}

Success (200 OK):

{
  "message": "OTP verified successfully",
  "verified": true,
  "method": "OTP" // or "Magic Link"
}

🎯 Enterprise Testing Scenarios

1. Magic Link Extraction (Interview Question)

// Cypress/Playwright: Extract token and visit
const response = await fetch('/api/v1/otp/inbox/test@example.com');
const { magicLink } = await response.json();
await page.goto(magicLink); // Auto-login!

2. Polling for Delayed Emails

// Recursive polling (Senior QA skill)
async function pollInbox(email, maxAttempts = 10) {
  for (let i = 0; i < maxAttempts; i++) {
    const res = await fetch(`/api/v1/otp/inbox/${email}`);
    if (res.status === 200) return res.json();
    if (res.status === 202) {
      await new Promise(r => setTimeout(r, 1000));
      continue;
    }
    throw new Error('OTP not found');
  }
}

3. Spam Folder Detection

// Test must check folder property
test('detects spam folder', async () => {
  await sendOTP({ triggerSpam: true });
  const inbox = await getInbox();
  
  // FAIL if you forget to check folder!
  expect(inbox.folder).toBe('SPAM');
});

Error Responses

The API uses standard HTTP status codes and returns error details in JSON format.

400 Bad Request

{
  "error": "Validation failed",
  "details": {
    "email": "Invalid email format"
  }
}

401 Unauthorized

{
  "error": "Authentication required",
  "message": "Please provide a valid JWT token"
}

404 Not Found

{
  "error": "Resource not found",
  "message": "The requested product does not exist"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "retryAfter": 60
}

Rate Limiting

⚠️ Rate Limits

  • Maximum 100 requests per minute per IP address or user
  • Rate limit information included in response headers:
    • X-RateLimit-Limit: Total requests allowed
    • X-RateLimit-Remaining: Requests remaining in window
    • Retry-After: Seconds to wait (on 429 errors)
  • Exceeding this limit will result in 429 Too Many Requests responses

Tools & Resources

Postman Collection

Import-ready collection with pre-configured requests, environment variables, and test scripts.

Download Collection

API Explorer

Interactive in-browser API testing with automatic code generation for multiple frameworks.

Open API Explorer

Need More Help?

Last updated: December 5, 2025

API Version: 1.0