Nutgraf API Documentation

Integrate AI-powered article summarization into your applications

Getting Started

The Nutgraf API allows you to programmatically access our article summarization capabilities. To get started:

  1. Generate an API key from your Settings page
  2. Include your API key in requests using the Authorization header
  3. Make requests to our REST endpoints

Authentication

All API requests must include your Nutgraf API key in one of these ways:

Authorization Header (Recommended)

Authorization: Bearer YOUR_NUTGRAF_API_KEY

X-API-Key Header (Alternative)

X-API-Key: YOUR_NUTGRAF_API_KEY

AI Provider API Keys

To use AI models, you need OpenAI or Anthropic API keys. You can provide them in two ways:

Option 1: Account Settings (Recommended)

Store your AI API keys in your account settings. They will be encrypted and used automatically.

Option 2: Per-Request Keys

Include AI API keys directly in your API requests using openai_api_key field.

Key Priority

1. Keys provided in the request (highest priority)
2. Keys stored in your account settings
3. Error if no valid key found for the requested model

Base URL

http://nutgraf.io/api/v1

Rate Limits

API usage is limited to 1,000 requests per month per account. Current usage can be checked via the /usage endpoint or your settings page.

Endpoints

Health Check

GET /v1/health

Check if the API is operational. No authentication required.

Response

{
  "status": "healthy",
  "service": "Nutgraf API",
  "version": "1.0.0",
  "timestamp": "2024-01-01T12:00:00"
}

Summarize Content

POST /v1/summarize

Generate a summary from a URL or provided text content.

Request Body

{
  "url": "https://example.com/article",  // Optional if text provided
  "text": "Article content...",          // Optional if url provided
  "title": "Article Title",             // Optional
  "length": "standard",                 // Optional: brief, standard, in_depth, custom
  "tone": "neutral",                    // Optional: neutral, conversational, professional
  "format": "prose",                    // Optional: prose, bullets
  "model": "gpt-3.5-turbo",            // Optional: AI model to use
  "custom_word_count": 300,            // Optional: if length is "custom"
  "save_summary": true,                 // Optional: save to your history
  "openai_api_key": "sk-..."           // Optional: OpenAI key for this request
  // "anthropic_api_key": "sk-ant-..."    // Optional: Anthropic key for this request
}

Response

{
  "summary": {
    "text": "Generated summary text...",
    "word_count": 150,
    "id": 123  // Only if save_summary=true
  },
  "metadata": {
    "title": "Article Title",
    "author": "Author Name",
    "url": "https://example.com/article",
    "length": "standard",
    "tone": "neutral",
    "format": "prose",
    "model": "gpt-3.5-turbo",
    "timestamp": "2024-01-01T12:00:00"
  },
  "usage": {
    "calls_made": 15,
    "calls_remaining": 985
  }
}

Get Usage Statistics

GET /v1/usage

Check your current API usage and account information.

Response

{
  "usage": {
    "calls_made": 15,
    "calls_limit": 1000,
    "calls_remaining": 985,
    "percentage_used": 1.5
  },
  "account": {
    "email": "user@example.com",
    "member_since": "2024-01-01T00:00:00"
  }
}

Get Available Models

GET /v1/models

Get a list of available AI models you can use for summarization.

Response

{
  "models": [
    {
      "id": "gpt-3.5-turbo",
      "name": "GPT-3.5 Turbo",
      "provider": "OpenAI"
    },
    // {
    //   "id": "claude-3-sonnet",
    //   "name": "Claude 3.5 Sonnet",
    //   "provider": "Anthropic"
    // }
  ],
  "default_model": "gpt-3.5-turbo"
}

Error Responses

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

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded your monthly limit of 1000 API calls",
  "usage": {
    "calls_made": 1000,
    "calls_limit": 1000
  }
}

Common Error Codes

  • 400 - Bad Request (missing required fields, invalid JSON)
  • 401 - Unauthorized (missing or invalid API key)
  • 403 - Forbidden (account disabled)
  • 429 - Too Many Requests (rate limit exceeded)
  • 500 - Internal Server Error

Code Examples

Python

Using stored API keys

import requests

nutgraf_api_key = "YOUR_NUTGRAF_API_KEY"
url = "http://nutgraf.io/api/v1/summarize"

headers = {
    "Authorization": f"Bearer {nutgraf_api_key}",
    "Content-Type": "application/json"
}

data = {
    "url": "https://example.com/article",
    "length": "standard",
    "tone": "neutral",
    "save_summary": True
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

if response.status_code == 200:
    print("Summary:", result["summary"]["text"])
    print("Word count:", result["summary"]["word_count"])
else:
    print("Error:", result["error"])

Providing AI API key in request

import requests

nutgraf_api_key = "YOUR_NUTGRAF_API_KEY"
openai_api_key = "sk-your-openai-key..."

url = "http://nutgraf.io/api/v1/summarize"

headers = {
    "Authorization": f"Bearer {nutgraf_api_key}",
    "Content-Type": "application/json"
}

data = {
    "url": "https://example.com/article",
    "length": "standard",
    "tone": "neutral", 
    "model": "gpt-4",
    "openai_api_key": openai_api_key,  # Provide OpenAI key for this request
    "save_summary": True
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

if response.status_code == 200:
    print("Summary:", result["summary"]["text"])
else:
    print("Error:", result["error"])

JavaScript (Node.js)

const axios = require('axios');

const apiKey = 'YOUR_API_KEY';
const url = 'http://nutgraf.io/api/v1/summarize';

const data = {
  url: 'https://example.com/article',
  length: 'standard',
  tone: 'neutral',
  save_summary: true
};

const headers = {
  'Authorization': `Bearer ${apiKey}`,
  'Content-Type': 'application/json'
};

axios.post(url, data, { headers })
  .then(response => {
    console.log('Summary:', response.data.summary.text);
    console.log('Word count:', response.data.summary.word_count);
  })
  .catch(error => {
    console.error('Error:', error.response.data.error);
  });

cURL

Using stored API keys

curl -X POST "http://nutgraf.io/api/v1/summarize" \
  -H "Authorization: Bearer YOUR_NUTGRAF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "length": "standard",
    "tone": "neutral",
    "save_summary": true
  }'

Providing AI API key in request

curl -X POST "http://nutgraf.io/api/v1/summarize" \
  -H "Authorization: Bearer YOUR_NUTGRAF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "length": "standard",
    "tone": "neutral",
    "model": "gpt-4",
    "openai_api_key": "sk-your-openai-key...",
    "save_summary": true
  }'

Best Practices

  • Rate limiting: Monitor your usage and implement client-side rate limiting
  • Error handling: Always check status codes and handle errors gracefully
  • Caching: Cache results when appropriate to reduce API calls
  • Security: Never expose API keys in client-side code or public repositories
  • API Key Storage: Store AI provider keys in your account settings when possible rather than sending them with each request
  • Content size: Very long articles may be truncated; consider preprocessing

Support

Need help with the API? Contact us or check your account settings for usage information.