GovPulse API Documentation

Getting Started

GovPulse provides AI-powered government intelligence through RESTful APIs and Watson Orchestrate integration. Get started in minutes with our comprehensive platform.

Base URL

Service Plans

Authentication

GovPulse uses API keys for authentication. Include your API key in the X-API-Key header with every request.

Getting Your API Key

1. Sign up at govpulse.io
2. Access your dashboard at dashboard.govpulse.io
3. Copy your API key from the API section

Authentication Example

curl -H "X-API-Key: your-api-key-here" \
  https://api.govpulse.io/v2/posts

API Reference

Posts Endpoint

Retrieve government news posts with AI-powered analysis.

curl -H "X-API-Key: your-api-key" \
  "https://api.govpulse.io/v2/posts?limit=10&category=contracts"

{
  "data": [
    {
      "id": "post-123",
      "title": "Department of Defense Announces New Cybersecurity Initiative",
      "content": "The Department of Defense today announced...",
      "category": "contracts",
      "url": "https://example.gov/news/...",
      "published_at": "2025-10-29T12:00:00Z",
      "sentiment": {
        "score": 0.7,
        "label": "positive",
        "confidence": 0.95
      },
      "entities": [
        {
          "text": "Department of Defense",
          "type": "organization",
          "confidence": 0.98
        }
      ],
      "ai_summary": "DoD launches comprehensive cybersecurity program..."
    }
  ],
  "pagination": {
    "total": 1250,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Briefings Endpoint

curl -H "X-API-Key: your-api-key" \
  "https://api.govpulse.io/v2/briefings?timeframe=7d&topics=cybersecurity,defense"

Search Endpoint

Watson Orchestrate Integration

GovPulse leverages IBM Watson Orchestrate for advanced AI capabilities including natural language processing, sentiment analysis, and automated workflow execution.

Watson-Powered Features

• Natural Language Understanding: Entity extraction and sentiment analysis
• Content Summarization: AI-generated briefings and summaries
• Semantic Search: Context-aware document search
• Workflow Automation: Custom automation chains

Watson Orchestrate Provisioning

GovPulse acts as a service broker for Watson Orchestrate through IBM Cloud. When you subscribe to GovPulse, we automatically provision Watson services for you.

# Watson features are automatically available with your GovPulse subscription
curl -H "X-API-Key: your-api-key" \
  "https://api.govpulse.io/v2/watson/analyze" \
  -d '{"text": "Analyze this government document for key insights"}'

Service Broker Details

Our Watson Orchestrate service broker is available at:

Webhooks

Receive real-time notifications when new government news is published or when AI analysis is complete.

Webhook Events

• post.created - New government news post published
• briefing.generated - Executive briefing generation complete
• analysis.completed - Watson analysis finished

Webhook Payload Example

{
  "event": "post.created",
  "timestamp": "2025-10-29T12:00:00Z",
  "data": {
    "post_id": "post-123",
    "title": "New Defense Contract Opportunity",
    "category": "contracts",
    "sentiment": "positive",
    "url": "https://api.govpulse.io/v2/posts/post-123"
  }
}

Rate Limits

API requests are subject to rate limits based on your subscription plan.

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1635552000

Error Handling

GovPulse uses standard HTTP status codes and provides detailed error messages in JSON format.

Error Response Format

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired",
    "details": {
      "request_id": "req-123456",
      "timestamp": "2025-10-29T12:00:00Z"
    }
  }
}

Common Error Codes

Code Examples

JavaScript/Node.js

const axios = require('axios');

const govpulse = axios.create({
  baseURL: 'https://api.govpulse.io/v2',
  headers: {
    'X-API-Key': 'your-api-key-here'
  }
});

// Get latest government news
async function getLatestNews() {
  try {
    const response = await govpulse.get('/posts', {
      params: { limit: 10, category: 'contracts' }
    });
    return response.data;
  } catch (error) {
    console.error('Error fetching news:', error.response.data);
  }
}

// Generate executive briefing
async function generateBriefing() {
  try {
    const response = await govpulse.get('/briefings', {
      params: { timeframe: '24h', format: 'html' }
    });
    return response.data;
  } catch (error) {
    console.error('Error generating briefing:', error.response.data);
  }
}

Python

import requests

class GovPulseClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://api.govpulse.io/v2'
        self.headers = {'X-API-Key': api_key}
    
    def get_posts(self, limit=20, category=None):
        params = {'limit': limit}
        if category:
            params['category'] = category
        
        response = requests.get(
            f'{self.base_url}/posts',
            headers=self.headers,
            params=params
        )
        return response.json()
    
    def search(self, query, semantic=True):
        params = {'q': query, 'semantic': semantic}
        response = requests.get(
            f'{self.base_url}/search',
            headers=self.headers,
            params=params
        )
        return response.json()

# Usage
client = GovPulseClient('your-api-key-here')
news = client.get_posts(limit=10, category='defense')
results = client.search('cybersecurity contracts')

cURL Examples

# Get recent posts
curl -H "X-API-Key: your-api-key" \
  "https://api.govpulse.io/v2/posts?limit=5"

# Search for specific topics
curl -H "X-API-Key: your-api-key" \
  "https://api.govpulse.io/v2/search?q=defense+spending"

# Generate briefing
curl -H "X-API-Key: your-api-key" \
  "https://api.govpulse.io/v2/briefings?timeframe=7d&format=json"

IBM Cloud Marketplace

GovPulse is available through the IBM Cloud Marketplace with integrated Watson Orchestrate provisioning.

Marketplace Benefits

• Unified billing through IBM Cloud
• Automatic Watson Orchestrate provisioning
• Enterprise-grade security and compliance
• Integration with existing IBM Cloud services

Getting Started via Marketplace

1. Visit the IBM Cloud Marketplace
2. Search for "GovPulse Government Intelligence Agent"
3. Choose your plan and provision the service
4. Access your dashboard and API keys

Changelog