REST API v1

API Documentation

Automate your content operations with the KuzeyOS REST API. All endpoints return JSON and require JWT Bearer token authentication.

Quick Start
  • Create Account
  • Define Doctrine
  • Voice Profile
  • First Draft
Content Lab
  • Draft Generation
  • Scoring System
  • Risk Analysis
  • Queue Management
Analytics
  • Overview
  • Cohort Analysis
  • Funnel Attribution
  • Experiment OS
Global Search
  • GET /api/search
  • Hybrid keyword search
  • Type filtering
  • Relevance ranking

Base URL

https://api.sosyalmedyax.com

Authentication

All API requests require an Authorization header. You can create your API key from Settings → API Keys.

Header

Authorization: Bearer YOUR_API_KEY

Code Examples

curl
curl -X GET "https://api.sosyalmedyax.com/api/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Global search
curl -X GET "https://api.sosyalmedyax.com/api/search?q=doctrine&types=posts,ideas" \
  -H "Authorization: Bearer YOUR_API_KEY"
Python
import requests

API_KEY = "your_api_key"
BASE_URL = "https://api.sosyalmedyax.com"

headers = {"Authorization": f"Bearer {API_KEY}"}

# List posts
posts = requests.get(f"{BASE_URL}/api/posts", headers=headers).json()

# Global search
results = requests.get(
    f"{BASE_URL}/api/search",
    headers=headers,
    params={"q": "doctrine", "types": "posts,ideas", "limit": 5}
).json()

# Add new idea
idea = requests.post(
    f"{BASE_URL}/api/ideas",
    headers=headers,
    json={"raw_idea": "Thread about AI agents", "source": "api"}
).json()
JavaScript
const API_KEY = "your_api_key";
const BASE_URL = "https://api.sosyalmedyax.com";

const headers = {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json",
};

// List posts
const posts = await fetch(`${BASE_URL}/api/posts`, { headers })
  .then(r => r.json());

// Global search
const results = await fetch(
  `${BASE_URL}/api/search?q=doctrine&types=posts,ideas`,
  { headers }
).then(r => r.json());

// Start opportunity scan
await fetch(`${BASE_URL}/api/opportunities/scan`, {
  method: "POST",
  headers,
});

Endpoint Reference

A

Authentication

POST/api/auth/loginUser login — returns access + refresh token
POST/api/auth/refreshGet new access token using refresh token
POST/api/auth/logoutEnd session, revoke refresh token
POST/api/auth/forgot-passwordSend password reset email
POST/api/auth/reset-passwordReset password with token
P

Posts & Drafts

GET/api/postsList all posts (with status filter)
POST/api/postsCreate new post
GET/api/posts/{id}Single post detail
PATCH/api/posts/{id}/statusUpdate post status (draft → approved → queued)
DELETE/api/posts/{id}Delete post
I

Ideas

GET/api/ideasList ideas
POST/api/ideasAdd new idea
POST/api/ideas/{id}/generateGenerate draft from idea (LLM)
DELETE/api/ideas/{id}Delete idea
S

Search

GET/api/searchGlobal search — posts, ideas, people, opportunities (q, types, limit parameters)
A

Analytics

GET/api/analytics/overviewGeneral performance metrics
GET/api/analytics/advancedCohort, format/hook/language analysis
GET/api/analytics/funnelFunnel attribution data
A

Audience

GET/api/audienceAudience CRM list
POST/api/audienceAdd new person
GET/api/audience/{id}Person detail + interaction history
O

Opportunities

GET/api/opportunitiesOpportunity list
POST/api/opportunities/scanStart manual opportunity scan
PATCH/api/opportunities/{id}Update opportunity status
N

Notifications

GET/api/notificationsNotification list (unread_only filter)
GET/api/notifications/streamSSE stream — real-time notifications
GET/api/notifications/unread-countUnread notification count
PATCH/api/notifications/{id}/readMark notification as read
W

Webhooks

GET/api/webhooksWebhook list
POST/api/webhooksCreate new webhook
PATCH/api/webhooks/{id}Update webhook
DELETE/api/webhooks/{id}Delete webhook
POST/api/webhooks/{id}/testSend test payload
GET/api/webhooks/{id}/logsDelivery logs
H

Help & Docs

GET/api/help/faqFAQ list — 4 categories, 14 questions
GET/api/changelogVersion history and changelog
GET/api/docs/sectionsDocs navigation sections

Rate Limiting

When the limit is exceeded, 429 Too Many Requests is returned. The Retry-After header indicates the wait time.

Auth endpoints

Brute force protection

5 req/min

LLM endpoints (Starter)

Draft generation, coach, radar

10 req/hour

LLM endpoints (Pro)

50 req/hour

LLM endpoints (Creator OS)

200 req/hour

General API

100 req/min

Webhook delivery

1000 req/min

HTTP Status Codes

200Success
201Created
400Bad request
401Authentication required
403Unauthorized access
404Not found
429Rate limit exceeded
500Server error

Global Search

Search across all content with a single endpoint.

GET /api/search?q=doctrine
posts
ideas
people
opportunities