API Endpoints

Pulpminer API endpoints are unique URLs that return JSON data from your configured webpages. This guide explains how to create, manage, and use your API endpoints effectively.

Creating an Endpoint

  1. Generate JSON

    • Enter webpage URL
    • Get AI-generated JSON
    • Customize structure if needed
  2. Configure Settings

    • Enable/disable caching
    • Review JSON format
    • Save configuration
  3. Get Endpoint URL

    • Endpoint format: https://api.pulpminer.com/external/{api_id}
    • Copy from dashboard
    • Note the API ID

Managing Endpoints

Dashboard Overview

Your API dashboard shows:

  • All active endpoints
  • Source URLs
  • Cache status
  • Last fetch time
  • Usage statistics

Endpoint Status

Monitor each endpoint’s:

  • Active/Inactive status
  • Cache configuration
  • Last update time
  • Response format

Using Endpoints

Making Requests

Basic Request

curl -H "apikey: YOUR_API_KEY" https://api.pulpminer.com/external/123

With Error Handling

async function fetchData(apiId) {
  try {
    const response = await fetch(
      `https://api.pulpminer.com/external/${apiId}`,
      {
        headers: {
          'apikey': 'YOUR_API_KEY'
        }
      }
    );
    
    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.errors[0].message);
    }
    
    return await response.json();
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}

Response Format

Success Response

{
  "data": {
    "title": "Example Page",
    "content": "Page content...",
    "metadata": {
      "author": "John Doe",
      "date": "2024-03-20"
    }
  },
  "errors": null
}

Error Response

{
  "data": null,
  "errors": [
    {
      "message": "error message here"
    }
  ]
}

Best Practices

1. Endpoint Management

  • Keep endpoints organized
  • Monitor usage patterns
  • Update configurations as needed
  • Document endpoint purposes

2. Error Handling

  • Implement proper error handling
  • Use retry logic
  • Monitor for failures
  • Log issues appropriately

3. Performance Optimization

  • Enable caching when appropriate
  • Monitor response times
  • Track usage patterns
  • Optimize request frequency

Implementation Examples

Node.js Service

class PulpminerService {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.pulpminer.com/external';
  }

  async fetchEndpoint(apiId) {
    try {
      const response = await fetch(`${this.baseUrl}/${apiId}`, {
        headers: {
          'apikey': this.apiKey
        }
      });

      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.errors[0].message);
      }

      return await response.json();
    } catch (error) {
      console.error(`Error fetching endpoint ${apiId}:`, error);
      throw error;
    }
  }
}

Python Client

import requests
from typing import Dict, Any

class PulpminerClient:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = 'https://api.pulpminer.com/external'

    def fetch_endpoint(self, api_id: str) -> Dict[str, Any]:
        try:
            response = requests.get(
                f'{self.base_url}/{api_id}',
                headers={'apikey': self.api_key}
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            print(f'Error fetching endpoint {api_id}: {e}')
            raise

Common Use Cases

1. Content Aggregation

// Fetch content from multiple endpoints
async function aggregateContent(endpoints) {
  const results = await Promise.all(
    endpoints.map(id => pulpminer.fetchEndpoint(id))
  );
  return results.map(r => r.data);
}

2. Data Monitoring

# Monitor endpoint for changes
def monitor_endpoint(api_id, interval_seconds):
    while True:
        data = client.fetch_endpoint(api_id)
        process_data(data)
        time.sleep(interval_seconds)

3. Data Integration

// Integrate with other systems
async function syncData(apiId, targetSystem) {
  const data = await pulpminer.fetchEndpoint(apiId);
  await targetSystem.update(data);
}

Troubleshooting

Common Issues

  1. Invalid Endpoint

    • Verify API ID
    • Check endpoint status
    • Confirm URL format
    • Test with curl
  2. Authentication Errors

    • Verify API key
    • Check header format
    • Confirm key is active
    • Test key separately
  3. Data Issues

    • Check source webpage
    • Verify JSON format
    • Review cache settings
    • Test endpoint directly

Monitoring

Key Metrics

  • Response time
  • Success rate
  • Error frequency
  • Usage patterns

Alerts

Set up alerts for:

  • Endpoint failures
  • High latency
  • Error spikes
  • Usage thresholds

Need Help?

If you’re having endpoint issues:

  1. Check endpoint status
  2. Verify configuration
  3. Test with curl
  4. Contact support at hello@pulpminer.com