API Getting Started

Learn how to integrate with the ChapterWise API for programmatic access to manuscript analysis

Last updated: 2025-01-17

API Getting Started

The ChapterWise API provides programmatic access to all manuscript analysis features, allowing you to integrate literary analysis capabilities into your own applications. This guide will get you started with authentication and basic API usage.

Overview

The ChapterWise API is a RESTful API that allows you to: - Upload and manage manuscripts - Run analysis modules programmatically - Retrieve analysis results in JSON format - Export data in multiple formats - Monitor analysis progress in real-time

Base URL: https://api.chapterwise.app/v1

Authentication

OAuth 2.0 Flow

ChapterWise uses OAuth 2.0 for secure API access. This allows users to authorize your application without sharing their passwords.

Step 1: Register Your Application

  1. Contact us at developers@chapterwise.app to register your application
  2. Provide your application name, description, and redirect URI
  3. Receive your client_id and client_secret

Step 2: Authorization Request

Redirect users to our authorization endpoint:

GET https://chapterwise.app/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=manuscripts:read analysis:read&
  state=RANDOM_STATE_STRING

Scopes Available: - manuscripts:read - Access user's manuscripts and metadata - analysis:read - Access analysis results - manuscripts:write - Upload and modify manuscripts (coming soon) - analysis:write - Run analysis modules (coming soon)

Step 3: Handle Authorization Response

Users will be redirected back to your application with an authorization code:

https://yourapp.com/callback?code=AUTHORIZATION_CODE&state=STATE_STRING

Step 4: Exchange Code for Access Token

curl -X POST https://chapterwise.app/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=YOUR_REDIRECT_URI"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def502003e8b...",
  "scope": "manuscripts:read analysis:read"
}

Step 5: Use Access Token

Include the access token in all API requests:

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://api.chapterwise.app/v1/manuscripts

Basic API Usage

Get User's Manuscripts

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://api.chapterwise.app/v1/manuscripts

Response:

{
  "manuscripts": [
    {
      "id": "manu_abc123",
      "title": "The Odyssey",
      "author": "Homer",
      "chapter_count": 24,
      "word_count": 12500,
      "created_at": "2025-01-15T10:30:00Z",
      "status": "analyzed"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

Get Manuscript Details

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://api.chapterwise.app/v1/manuscripts/manu_abc123

Response:

{
  "id": "manu_abc123",
  "title": "The Odyssey",
  "author": "Homer",
  "chapters": [
    {
      "id": "ch_001",
      "number": 1,
      "title": "Book I: Athena Inspires the Prince",
      "word_count": 520,
      "has_analysis": true
    }
  ],
  "analysis_modules_available": [
    "summary", "characters", "heros_journey", "story_beats"
  ]
}

Get Analysis Results

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://api.chapterwise.app/v1/manuscripts/manu_abc123/analysis/characters

Response:

{
  "manuscript_id": "manu_abc123",
  "module": "characters",
  "book_results": {
    "main_characters": [
      {
        "name": "Odysseus",
        "archetype": "The Hero",
        "mentions": 89,
        "relationships": ["Penelope (spouse)", "Telemachus (son)"],
        "character_arc": "Clever wanderer seeking homecoming and redemption"
      },
      {
        "name": "Athena",
        "archetype": "The Mentor", 
        "mentions": 56,
        "relationships": ["Odysseus (protégé)", "Telemachus (guide)"],
        "character_arc": "Divine wisdom guiding mortal heroes"
      }
    ]
  },
  "chapter_results": [
    {
      "chapter_number": 1,
      "chapter_characters": [
        {
          "name": "Telemachus",
          "count": 12,
          "archetypes": ["The Innocent", "The Seeker"]
        }
      ]
    }
  ]
}

Code Examples

Python Example

import requests
import json

class ChapterWiseAPI:
    def __init__(self, access_token):
        self.base_url = "https://api.chapterwise.app/v1"
        self.headers = {
            "Authorization": f"Bearer {access_token}",
            "Content-Type": "application/json"
        }

    def get_manuscripts(self):
        response = requests.get(f"{self.base_url}/manuscripts", headers=self.headers)
        return response.json()

    def get_analysis(self, manuscript_id, module):
        response = requests.get(
            f"{self.base_url}/manuscripts/{manuscript_id}/analysis/{module}", 
            headers=self.headers
        )
        return response.json()

    def export_analysis(self, manuscript_id, format="json"):
        response = requests.get(
            f"{self.base_url}/manuscripts/{manuscript_id}/export",
            headers=self.headers,
            params={"format": format}
        )
        return response.content

# Usage
api = ChapterWiseAPI("your_access_token_here")
manuscripts = api.get_manuscripts()
analysis = api.get_analysis("manu_abc123", "characters")

JavaScript/Node.js Example

const axios = require('axios');

class ChapterWiseAPI {
  constructor(accessToken) {
    this.baseURL = 'https://api.chapterwise.app/v1';
    this.headers = {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json'
    };
  }

  async getManuscripts() {
    try {
      const response = await axios.get(`${this.baseURL}/manuscripts`, {
        headers: this.headers
      });
      return response.data;
    } catch (error) {
      console.error('Error fetching manuscripts:', error.response.data);
      throw error;
    }
  }

  async getAnalysis(manuscriptId, module) {
    try {
      const response = await axios.get(
        `${this.baseURL}/manuscripts/${manuscriptId}/analysis/${module}`,
        { headers: this.headers }
      );
      return response.data;
    } catch (error) {
      console.error('Error fetching analysis:', error.response.data);
      throw error;
    }
  }
}

// Usage
const api = new ChapterWiseAPI('your_access_token_here');

async function analyzeManuscript() {
  const manuscripts = await api.getManuscripts();
  const firstManuscript = manuscripts.manuscripts[0];

  const characterAnalysis = await api.getAnalysis(
    firstManuscript.id, 
    'characters'
  );

  console.log('Main characters:', characterAnalysis.book_results.main_characters);
}

cURL Examples

Get all analysis for a manuscript:

#!/bin/bash
MANUSCRIPT_ID="manu_abc123"
ACCESS_TOKEN="your_access_token"

for module in summary characters heros_journey story_beats; do
  echo "Fetching $module analysis..."
  curl -H "Authorization: Bearer $ACCESS_TOKEN" \
    "https://api.chapterwise.app/v1/manuscripts/$MANUSCRIPT_ID/analysis/$module" \
    -o "${module}_analysis.json"
done

Export complete analysis report:

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://api.chapterwise.app/v1/manuscripts/manu_abc123/export?format=pdf" \
  -o "odyssey_analysis_report.pdf"

Rate Limiting

API requests are rate limited to ensure fair usage:

  • Free tier: 100 requests per hour
  • Paid accounts: 1,000 requests per hour
  • Enterprise: Custom limits

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Error Handling

Standard Error Response

{
  "error": {
    "code": "INVALID_MANUSCRIPT",
    "message": "Manuscript not found or access denied",
    "details": {
      "manuscript_id": "manu_invalid123",
      "user_id": "user_xyz789"
    }
  }
}

Common Error Codes

Code HTTP Status Description
INVALID_TOKEN 401 Access token is invalid or expired
INSUFFICIENT_SCOPE 403 Token doesn't have required permissions
MANUSCRIPT_NOT_FOUND 404 Requested manuscript doesn't exist
ANALYSIS_PENDING 202 Analysis is still in progress
RATE_LIMIT_EXCEEDED 429 Too many requests

Webhooks

Subscribe to real-time updates about analysis progress:

Webhook Events

  • analysis.completed - Analysis module finished
  • analysis.failed - Analysis module encountered an error
  • manuscript.uploaded - New manuscript uploaded (coming soon)

Example Webhook Payload

{
  "event": "analysis.completed",
  "data": {
    "manuscript_id": "manu_abc123",
    "module": "characters",
    "status": "completed",
    "completed_at": "2025-01-17T15:30:00Z"
  },
  "user_id": "user_xyz789"
}

Next Steps

Learn More

Get Help

Example Applications

  • Academic Research: Bulk analysis of literary corpora
  • Writing Tools: Integrate analysis into writing software
  • Educational Platforms: Add literary analysis to learning management systems
  • Publishing Workflows: Automate manuscript evaluation processes

Ready to build? Register your application to get started with the ChapterWise API.