# Getting Started with the Veritas B2B API

This guide will help you get started with the Veritas News B2B API.

## Prerequisites

- A Veritas B2B API key
- Basic knowledge of REST APIs
- An HTTP client or one of our official SDKs

## Obtaining API Keys

### Production Keys

Production API keys begin with `sk_live_` and provide access to real news data.
Contact our sales team at sales@veritas.news to obtain production credentials.

### Test Keys

Test API keys begin with `sk_test_` and connect to our sandbox environment with
mock data. Test keys are ideal for development and integration testing.

## Authentication

All API requests require authentication using your API key. You can provide your
key in two ways:

### X-API-Key Header (Recommended)

```bash
curl -H "X-API-Key: sk_live_your_api_key" \
  https://api.veritas.news/api/v1/b2b/feed
```

### Authorization Bearer Token

```bash
curl -H "Authorization: Bearer sk_live_your_api_key" \
  https://api.veritas.news/api/v1/b2b/feed
```

## Making Your First Request

### Using cURL

```bash
# List recent articles
curl -X GET "https://api.veritas.news/api/v1/b2b/feed?limit=5" \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json"
```

### Using JavaScript SDK

```bash
npm install @veritas/b2b-sdk
```

```javascript
import { VeritasClient } from '@veritas/b2b-sdk';

const client = new VeritasClient({
  apiKey: 'sk_live_your_api_key',
});

// List articles
const { items } = await client.feed.list({ limit: 5 });
console.log(items);

// Search articles
const results = await client.search.query({ q: 'climate change' });
console.log(`Found ${results.total} articles`);
```

### Using Python SDK

```bash
pip install veritas-sdk
```

```python
from veritas_sdk import VeritasClient

client = VeritasClient(api_key="sk_live_your_api_key")

# List articles
response = await client.feed.list(limit=5)
for article in response["items"]:
    print(article["headline"])

# Search articles
results = await client.search.query(q="climate change")
print(f"Found {results['total']} articles")
```

## Response Format

All API responses are JSON with consistent structure:

### List Responses

```json
{
  "items": [...],
  "nextCursor": "cursor_token_for_next_page"
}
```

### Single Item Responses

```json
{
  "article": { ... }
}
```

### Search Responses

```json
{
  "items": [...],
  "total": 1234,
  "page": 1,
  "pageSize": 20,
  "totalPages": 62,
  "aggregations": { ... }
}
```

## Pagination

The API uses cursor-based pagination for list endpoints:

```bash
# First page
curl "https://api.veritas.news/api/v1/b2b/feed?limit=20"

# Response includes nextCursor
{
  "items": [...],
  "nextCursor": "abc123"
}

# Next page
curl "https://api.veritas.news/api/v1/b2b/feed?limit=20&cursor=abc123"
```

With SDKs, use the iterator methods for automatic pagination:

```javascript
// JavaScript - iterate through all articles
for await (const article of client.feed.iterate({ category: 'politics' })) {
  console.log(article.headline);
}
```

```python
# Python - iterate through all articles
async for article in client.feed.iterate(category="politics"):
    print(article["headline"])
```

## Common Use Cases

### News Aggregation

```javascript
// Get latest articles by category
const politics = await client.feed.list({ category: 'politics', limit: 10 });
const business = await client.feed.list({ category: 'business', limit: 10 });
const tech = await client.feed.list({ category: 'technology', limit: 10 });
```

### Fact-Checking

```javascript
// Verify a claim
const claim = await client.claims.verify('COVID vaccines cause autism');
if (claim) {
  console.log(`Verdict: ${claim.verdict}`);
  console.log(`Evidence: ${claim.evidenceSummary}`);
}
```

### Entity Tracking

```javascript
// Track mentions of a person
const entity = await client.entities.search({ q: 'Elon Musk', type: 'person' });
const articles = await client.entities.articles(entity.entities[0].id);
```

### Breaking News Alerts

```javascript
// Create a breaking news alert
await client.alerts.createBreakingNewsAlert('Politics Alert', {
  categories: ['politics'],
  webhookUrl: 'https://your-server.com/webhook',
  frequency: 'instant',
});
```

## Best Practices

1. **Use SDKs** - Our official SDKs handle authentication, retries, and
   pagination automatically.

2. **Implement Rate Limiting** - Respect rate limits and implement exponential
   backoff for retries.

3. **Use Sandbox for Development** - Test with `sk_test_` keys before using
   production credentials.

4. **Cache Responses** - Cache article content and only fetch updates using date
   filters.

5. **Use Pagination** - Never request more than 100 items at once; use cursors
   for large datasets.

6. **Handle Errors Gracefully** - Implement proper error handling for all API
   calls.

## Next Steps

- [API Reference](./api-reference.md) - Detailed endpoint documentation
- [Error Handling](./error-handling.md) - Error codes and recovery
- [Webhooks](./webhooks.md) - Set up real-time notifications
- [Sandbox](./sandbox.md) - Testing environment guide
