# Company Needs API
> Summarize recent pain points, challenges, or other requested content from a company's official filings. Returns concise, structured highlights.
**Base URL:** `https://api.nyne.ai`
**Endpoint:** `https://api.nyne.ai/company/needs`

---

## Overview
The Company Needs API analyzes a company's official SEC filings to surface business challenges, pain points, and strategic needs on a specified topic. Delivery is asynchronous: submit a request, receive a request_id, then poll or register a callback.
### What You Get
- **SEC Filing Analysis:** Surfaces challenges and pain points from official company filings- **Topic-Focused:** Specify the exact topic to surface (e.g. regulatory, supply chain)- **Filing Type Filters:** Optionally restrict to specific filing types (10-K, 8-K, etc.)- **Async Delivery:** Submit and poll or register a callback for results
## 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

- **Needs Analysis:** 3 credits per completed analysis
> Credits are charged when the analysis produces results. If no relevant filings are found, no credits are charged.
---

## POST /company/needsQueue a filing analysis request to surface business pain points and challenges.
### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `company_name` | string | Yes | Company to analyze (e.g. "Uber Technologies, Inc."). |
| `content` | string | Yes | Topic to surface (e.g. "Regulatory challenges", "Supply chain issues"). |
| `filing` | string | No | Restrict to a filing type (e.g. "Form 10-K", "Form 8-K"). |
| `callback_url` | string | No | HTTPS endpoint to receive the completed payload automatically. |

> **Required:** Both company_name and content are required.
### Request Examples

**With Advanced Features:**

```json
{
  "company_name": "Uber Technologies, Inc.",
  "content": "Regulatory challenges",
  "filing": "Form 10-K",
  "callback_url": "https://example.com/webhooks/company-needs"
}
```

**Basic Request:**

```json
{
  "company_name": "Apple Inc.",
  "content": "Supply chain challenges"
}
```

### Code Examples

**cURL:**

```bash
curl -X POST https://api.nyne.ai/company/needs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Apple Inc.",
    "content": "Supply chain challenges"
  }'
```

**Python:**

```python
import requests
import json

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

data = {
    "company_name": "Apple Inc.",
    "content": "Supply chain challenges"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(json.dumps(result, indent=2))
```

**JavaScript:**

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

const data = {
    company_name: "Apple Inc.",
    content: "Supply chain challenges"
};

fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(result => console.log(result))
.catch(error => console.error("Error:", error));
```

**PHP:**

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

$data = [
    "company_name" => "Apple Inc.",
    "content" => "Supply chain challenges"
];

$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);
curl_close($ch);

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

### Response Codes

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

### Response Example

```json
{
  "success": true,
  "data": {
    "request_id": "coneeds_64f2d8e4_1700000456",
    "status": "queued",
    "message": "Company needs request queued. Use GET /company/needs?request_id=... to check status.",
    "callback_url": "https://example.com/webhooks/company-needs"
  },
  "timestamp": "2025-11-10T22:32:03Z"
}
```

---

## GET /company/needs
Check the status of a request.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `request_id` | string | Yes | Identifier returned by the POST call |

### Request Example

```
GET /company/needs?request_id=coneeds_64f2d8e4_1700000456
```

### 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": "coneeds_64f2d8e4_1700000456",
    "status": "completed",
    "result": {
      "company": "Uber Technologies, Inc.",
      "needs": [
        {
          "filing": "Form 10-K",
          "content": "Notes increased regulatory compliance costs in multiple regions.",
          "filing_date": "2025-02-14",
          "source_url": "https://www.sec.gov/Archives/edgar/data/0001543151/000154315125000012/uber-20241231x10k.htm"
        }
      ]
    },
    "created_on": "2025-11-10T22:32:03Z",
    "completed_on": "2025-11-10T22:32:41Z"
  },
  "timestamp": "2025-11-10T22:32:41Z"
}
```

---

## Response Format

All API responses follow a consistent JSON format. All fields in enrichment results are **optional** and only included when data is available:
- Results include filing type, extracted content summary, filing date, and source URL- The needs array contains one entry per matching filing excerpt- If no relevant filings are found, the needs array will be empty and no credits are charged
---

## Error Codes

| HTTP Code | Error Code | Description |
|-----------|------------|-------------|
| 400 | `missing_parameters` | company_name or content omitted |
| 400 | `invalid_callback_url` | Callback URL must be HTTPS |
| 403 | `subscription_required` | Account lacks enrichment product access |
| 402 | `insufficient_credits` | Not enough credits available |
| 429 | `rate_limit_exceeded` | Usage limits exceeded |
| 429 | `monthly_limit_exceeded` | Monthly usage limit exceeded |

---

## 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
POST https://example.com/webhooks/company-needs
Content-Type: application/json

{
  "request_id": "coneeds_64f2d8e4_1700000456",
  "status": "completed",
  "result": {
    "company": "Uber Technologies, Inc.",
    "needs": [
      {
        "filing": "Form 10-K",
        "content": "Notes increased regulatory compliance costs in multiple regions.",
        "filing_date": "2025-02-14",
        "source_url": "https://www.sec.gov/Archives/edgar/data/0001543151/000154315125000012/uber-20241231x10k.htm"
      }
    ]
  },
  "created_at": "2025-11-10T22:32:03Z",
  "completed_at": "2025-11-10T22:32:41Z"
}
```

---

## Best Practices

Prioritize inputs in this order for best match rates:
1. **Specific Topics** (Best) — Use precise content queries like "Regulatory compliance costs" rather than broad terms.2. **Filing Type Filter** (Recommended) — Restrict to 10-K or 10-Q for comprehensive annual/quarterly analysis.
---

## Note for AI Agents
This is an asynchronous API. Submit via POST, then poll GET with the returned request_id until status is completed. Typical processing time is 15-60 seconds depending on filing volume. Both company_name and content are required. Use callback_url for production workflows.
---

## Related APIs
- **Company Enrichment API** — Full company profile → `https://api.nyne.ai/documentation/company/enrichment`
- **Company Funding API** — Funding and investment data → `https://api.nyne.ai/documentation/company/funding`