# Person Article Search API
> Discover articles, publications, interviews, podcasts, and research papers about a person
**Base URL:** `https://api.nyne.ai`
**Endpoint:** `https://api.nyne.ai/person/articlesearch`

---

## Overview
The Person Article Search API helps you find published content about or by a specific person. Simply provide a person's name and their company, and get back a curated list of relevant articles, interviews, podcasts, and more. This API uses asynchronous processing: when you submit a request, it is queued for processing and you receive a request_id. Use this request_id to check the status and retrieve results when processing is complete.
### What You Get
- **Articles & Blog Posts:** News articles, blog posts, and written publications featuring the person- **Podcast Appearances:** Podcast episodes and audio interviews- **Video Content:** YouTube videos, interviews, and recorded presentations- **Research Papers:** Academic papers and research publications- **Ranked Results:** Results sorted by recency or popularity with relevance scoring- **Content Metadata:** Titles, summaries, keywords, and publication dates for each result
## Authentication

All requests require header authentication:

```
X-API-Key: YOUR_API_KEY
X-API-Secret: YOUR_API_SECRET
```

## Rate Limits

| Limit | Value |
|-------|-------|
| Per Minute | 60 requests |
| Per Hour | 1000 requests |
| Monthly | Varies by plan |

### Response Headers

Responses from endpoints that perform rate-limit checks include both legacy and standard rate-limit headers:

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Active per-minute or per-hour limit |
| `X-RateLimit-Remaining` | Remaining requests in the active window |
| `X-RateLimit-Reset` | Unix timestamp when the active window resets |
| `RateLimit-Limit` | Active per-minute or per-hour limit |
| `RateLimit-Remaining` | Remaining requests in the active window |
| `RateLimit-Reset` | Seconds until the active window resets |
| `Retry-After` | Seconds to wait before retrying; present on HTTP `429` rate-limit responses |

Monthly quota responses include quota-specific headers when available:

| Header | Description |
|--------|-------------|
| `X-Quota-Limit` | Monthly request or credit limit |
| `X-Quota-Used` | Amount used in the current billing cycle |
| `X-Quota-Remaining` | Amount remaining in the current billing cycle |
| `X-Quota-Reset` | Unix timestamp when the current billing cycle resets |

## Credit Usage

- **Article Search:** 4 credits per article search request
> Credits are charged per search request, regardless of the number of articles returned.
---

## POST /person/articlesearchSubmit a request to search for articles, publications, interviews, podcasts, and research papers about a person. The request is queued for asynchronous processing and returns a request_id to check status and retrieve results.
### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | The person's name to search for |
| `company` | string | Yes | The company name or domain where the person works |
| `sort` | string | No | Sort order for results: "recent" (by publication date, most recent first) or "popular" (by popularity and relevance) (default: `recent`) |
| `limit` | integer | No | Maximum number of results to return (max: 20) (default: `5`) |
| `callback_url` | string | No | HTTPS endpoint to receive results when processing is complete |

> **Required:** Both name and company are required.
### Request Examples

**With Advanced Features:**

```json
{
  "name": "John Doe",
  "company": "Acme Corp",
  "sort": "recent",
  "limit": 10,
  "callback_url": "https://yourapp.com/webhook/articlesearch"
}
```

**Basic Request:**

```json
{
  "name": "John Doe",
  "company": "Acme Corp"
}
```

### Code Examples

**cURL:**

```bash
# Step 1: Submit a search request
curl -X POST "https://api.nyne.ai/person/articlesearch" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "company": "Acme Corp",
    "sort": "recent",
    "limit": 5
  }'

# Step 2: Check status and get results
curl -X GET "https://api.nyne.ai/person/articlesearch?request_id=YOUR_REQUEST_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

**Python:**

```python
import requests
import json
import time

url = "https://api.nyne.ai/person/articlesearch"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json"
}

# Step 1: Submit search request
data = {
    "name": "John Doe",
    "company": "Acme Corp",
    "sort": "recent",
    "limit": 5
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
request_id = result["data"]["request_id"]
print(f"Request ID: {request_id}")

# Step 2: Poll for results
while True:
    status_response = requests.get(
        f"{url}?request_id={request_id}",
        headers=headers
    )
    status = status_response.json()
    if status["data"]["status"] in ["completed", "failed"]:
        print(json.dumps(status, indent=2))
        break
    time.sleep(5)
```

**JavaScript:**

```javascript
const url = "https://api.nyne.ai/person/articlesearch";
const headers = {
    "X-API-Key": "YOUR_API_KEY",
    "X-API-Secret": "YOUR_API_SECRET",
    "Content-Type": "application/json"
};

const data = {
    name: "John Doe",
    company: "Acme Corp",
    sort: "recent",
    limit: 5
};

// Step 1: Submit search request
fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(result => {
    const requestId = result.data.request_id;
    console.log("Request ID:", requestId);

    // Step 2: Check status
    return fetch(url + "?request_id=" + encodeURIComponent(requestId), { headers });
})
.then(response => response.json())
.then(status => console.log(status))
.catch(error => console.error("Error:", error));
```

**PHP:**

```php
<?php
$url = "https://api.nyne.ai/person/articlesearch";
$headers = [
    "X-API-Key: YOUR_API_KEY",
    "X-API-Secret: YOUR_API_SECRET",
    "Content-Type: application/json"
];

// Step 1: Submit search request
$data = [
    "name" => "John Doe",
    "company" => "Acme Corp",
    "sort" => "recent",
    "limit" => 5
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$result = json_decode($response, true);
$requestId = $result["data"]["request_id"];
echo "Request ID: " . $requestId . "\n";

// Step 2: Check status
curl_setopt($ch, CURLOPT_URL, $url . "?request_id=" . $requestId);
curl_setopt($ch, CURLOPT_POST, false);
curl_setopt($ch, CURLOPT_HTTPHEADER, array_slice($headers, 0, 2));

$statusResponse = curl_exec($ch);
$status = json_decode($statusResponse, true);
curl_close($ch);

echo json_encode($status, JSON_PRETTY_PRINT);
?>
```

### Response Codes

| Code | Description |
|------|-------------|
| 200 | Article search request queued successfully |
| 400 | Invalid or missing request parameters |
| 401 | Invalid API credentials |
| 402 | Insufficient credits |
| 429 | Rate limit exceeded |

### Response Example

```json
{
  "success": true,
  "data": {
    "request_id": "abc123def456",
    "status": "queued",
    "message": "Article search request queued. Use GET /person/articlesearch?request_id=... to check status."
  }
}
```

---

## GET /person/articlesearch
Check the status of a request.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `request_id` | string | Yes | The request ID returned from the POST request |

### Request Example

```
GET /person/articlesearch?request_id=abc123def456
```

### Response Codes

| Code | Description |
|------|-------------|
| 200 | Status retrieved successfully |
| 400 | Invalid request parameters |
| 401 | Invalid API credentials |
| 404 | Request ID not found |

### Response Example

```json
{
  "success": true,
  "data": {
    "request_id": "abc123def456",
    "status": "completed",
    "completed": true,
    "data": {
      "articles": [
        {
          "link": "https://example.com/article",
          "summary": "Brief summary of the content",
          "title": "Title of the page or content",
          "type": "article",
          "keywords": ["keyword1", "keyword2", "keyword3"],
          "date": {
            "year": 2024,
            "month": 1,
            "day": 15
          },
          "sortrank": 1,
          "ranktype": "recent"
        },
        {
          "link": "https://example.com/podcast-episode",
          "summary": "Podcast interview discussing leadership and innovation",
          "title": "Leadership Insights Podcast - Episode 42",
          "type": "podcast",
          "keywords": ["leadership", "innovation", "technology"],
          "date": {
            "year": 2024,
            "month": 1,
            "day": 10
          },
          "sortrank": 2,
          "ranktype": "recent"
        }
      ],
      "count": 2
    },
    "error": null,
    "created_on": "2024-01-15T10:30:00Z",
    "completed_on": "2024-01-15T10:35:00Z"
  }
}
```

---

## Response Format

All API responses follow a consistent JSON format. All fields in enrichment results are **optional** and only included when data is available:
- All API responses follow a consistent JSON format with a success boolean and data object- Article results are returned in the data.articles array- Each article includes link, summary, title, type, keywords, date, sortrank, and ranktype- The type field indicates the content type: article, podcast, youtube, or research_paper- The date object contains year, month, and day as integers- The count field indicates the total number of articles returned
---

## Error Codes

| HTTP Code | Error Code | Description |
|-----------|------------|-------------|
| 400 | `missing_parameters` | Required parameters are missing (name or company) |
| 400 | `invalid_parameters` | Invalid parameter values (e.g., invalid sort value) |
| 401 | `missing_credentials` | API key or secret is missing |
| 401 | `invalid_credentials` | API key or secret is invalid |
| 402 | `insufficient_credits` | Insufficient credits to complete the request |
| 429 | `rate_limit_exceeded` | Rate limit has been exceeded |
| 500 | `internal_error` | An internal server error occurred |

---

## Callbacks

When you provide a `callback_url`, the API sends results to your endpoint via HTTP POST.

### Retry Policy- Maximum 5 retry attempts- Exponential backoff: 1s, 5s, 15s, 1m, 5m- 30-second timeout per request- Your endpoint should return HTTP 2xx for success
Your callback endpoint should respond with HTTP 200-299. Any other code triggers a retry.

### Callback Payload Example

```json
{
  "request_id": "abc123def456",
  "status": "completed",
  "completed": true,
  "data": {
    "articles": [
      {
        "link": "https://example.com/article",
        "summary": "Brief summary",
        "title": "Article Title",
        "type": "article",
        "keywords": ["keyword1", "keyword2"],
        "date": { "year": 2024, "month": 1, "day": 15 }
      }
    ],
    "count": 1
  },
  "error": null,
  "timestamp": "2024-01-15T10:35:00Z"
}
```

---

## Related APIs
- **Person Enrichment API** — Get full profile for article subjects → `https://api.nyne.ai/documentation/person/enrichment`
- **Deep Research API** — Combines articles with enrichment data → `https://api.nyne.ai/documentation/person/deep-research`