Overview

The Network Intelligence API lets you map to people we can derive someone knows.

Authentication

All API requests require authentication using your API key and secret. You can authenticate using either HTTP headers (recommended) or query parameters.

X-API-Key: your_api_key_hereX-API-Secret: your_api_secret_here

Rate Limits

API usage is controlled by rate limiting mechanisms to ensure fair usage and system stability:

• Per Minute: 60 requests
• Per Hour: 1000 requests
• Monthly: Varies by plan

Credit Usage

API credits are consumed based on the network intelligence request:

• Network Intelligence Request: 3 credits per successful lookup

POST /person/interactions

Submit a request to map to people we can derive someone knows.

curl -X POST https://api.nyne.ai/person/interactions \
  -H "X-API-Key: your_api_key_here" \
  -H "X-API-Secret: your_api_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "replies",
    "social_media_url": "https://social-profile.example/johndoe/post/1234567890"
  }'

import requests
import json

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

data = {
    "type": "replies",
    "social_media_url": "https://social-profile.example/johndoe/post/1234567890"
}

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

const url = "https://api.nyne.ai/person/interactions";
const headers = {
    "X-API-Key": "your_api_key_here",
    "X-API-Secret": "your_api_secret_here",
    "Content-Type": "application/json"
};

const data = {
    type: "replies",
    social_media_url: "https://social-profile.example/johndoe/post/1234567890"
};

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
$url = "https://api.nyne.ai/person/interactions";
$headers = [
    "X-API-Key: your_api_key_here",
    "X-API-Secret: your_api_secret_here",
    "Content-Type: application/json"
];

$data = [
    "type" => "replies",
    "social_media_url" => "https://social-profile.example/johndoe/post/1234567890"
];

$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);
?>

GET /person/interactions

Check the status of a network intelligence request and retrieve results.

Request Type: Conversation Signals

Map to people connected to a specific post.

Example Request

Response Fields

• username: handle of the replier
• display_name: Display name
• reply_text: Content of the reply
• reply_date: When the reply was posted
• likes_count: Number of likes on the reply
• retweets_count: Number of retweets

Request Type: Audience Signals

Map to people connected to an account.

Example Request

Response Fields

• username: handle of the follower
• display_name: Display name
• bio: User biography
• followers_count: Their follower count
• following_count: How many they follow
• verified: Verification status

Request Type: Affinity Signals

Map to people associated with an account.

Example Request

Usage Statistics

Usage statistics are available through the unified usage API at /usage. This endpoint provides comprehensive usage information including credits used, monthly allocation, and breakdown by API type.

Response Format

All API responses follow a consistent JSON format:

Success Response

Error Response

Error Codes

The API returns structured error responses with specific error codes to help you handle issues programmatically.

Authentication Errors (401)

Validation Errors (400)

Authorization Errors (403)

Not Found Errors (404)

Rate Limit Errors (429)

Server Errors (500)

Error Response Example

Callback System

When you provide a callback_url, the API will send the interaction results to your endpoint via HTTP POST when processing is complete.

Callback Request Format

Callback 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

Callback Error Format

Important: Your callback endpoint should respond with HTTP 200-299 to indicate successful receipt. Any other response code will trigger a retry.