# Hordus AI — API Agent Guide
# Scope: All /api/v1/* endpoints and integration patterns
# Full documentation: https://hordus.ai/llms-full.txt
# OpenAPI Spec: https://hordus.ai/openapi.json

## Quick Reference

Base URL: https://hordus.ai/api/v1
Content-Type: application/json
Auth Header: X-API-Key: {your-key}
Rate Limit: 100 req/min | Status: https://hordus.ai/api/v1/info

## Authentication Methods

### Method 1: API Key (Recommended for Server-to-Server)
Header: X-API-Key: hordus_live_xxxxxxxxxxxx
Obtain at: https://hordus.ai/developers

### Method 2: OAuth 2.0 Bearer Token (Recommended for Agent Delegation)
Authorization URL: https://hordus.ai/oauth/authorize
Token URL: https://hordus.ai/oauth/token
Scopes:
  - read:visibility     — Read brand AI visibility scores
  - read:citations      — Read citation data
  - read:journeys       — Read journey trace data
  - write:prompts       — Submit prompts for analysis

## Endpoint Reference

### GET /api/v1/info
Auth: None
Response:
  {
    "name": "Hordus AI",
    "version": "1.0.0",
    "status": "operational",
    "capabilities": [...],
    "documentation": "https://hordus.ai/developers"
  }
When to call: Agent startup / capability discovery

---

### GET /api/v1/brand/{brandId}/visibility
Auth: Required (read:visibility)
Path params: brandId (string) — brand identifier (e.g., "acme-corp")
Query params:
  - platform: chatgpt | claude | gemini | perplexity | ai_overviews | all (default: all)
  - date_from: ISO 8601 (default: 7 days ago)
  - date_to: ISO 8601 (default: now)
Response fields:
  - visibility_score: float (0.0–1.0)
  - asov_percentage: float — Answer Share of Voice %
  - platform_breakdown: object per engine
  - trend: "up" | "down" | "stable"
Latency: Up to 3 seconds for real-time inference

---

### GET /api/v1/brand/{brandId}/citations
Auth: Required (read:citations)
Response fields:
  - total_citations: integer
  - by_domain: array of { domain, type, count, percentage }
  - by_type: { brand, reference, editorial, other }
  - top_competitor_citations: array

---

### GET /api/v1/competitive/{brandId}/leaderboard
Auth: Required (read:visibility)
Response: Ranked array of competitors with visibility scores in same vertical.

---

### GET /api/v1/journeys
Auth: Required (read:journeys)
Query params: date_from, date_to, platform, market (ISO 2-letter code)
Response: Aggregated, privacy-safe journey paths from AI prompt to conversion event.

---

### POST /api/v1/prompts/analyze
Auth: Required (write:prompts)
Body:
  {
    "prompts": ["what is the best FP&A tool?"],
    "brand_id": "acme-corp",
    "market": "US"
  }
Response:
  - intent_classification: string
  - citation_opportunity_score: float (0.0–1.0)
  - recommended_content_types: array

---

## MCP (Model Context Protocol)

Server Manifest: https://hordus.ai/.well-known/mcp/server-card.json
WebMCP Transport: wss://hordus.ai/api/mcp/transport
Protocol: MCP v1.0 with JSON-RPC 2.0

Available MCP Tools:
  - hordus.getBrandVisibility(brandId, platform?)
  - hordus.getCitations(brandId, dateRange?)
  - hordus.getCompetitorLeaderboard(brandId)
  - hordus.analyzePrompt(prompt, brandId)

## Error Codes

| Code | Message | Resolution |
|------|---------|------------|
| 400 | Bad Request | Check request body schema |
| 401 | Unauthorized | Verify X-API-Key header |
| 403 | Forbidden | Check OAuth scope |
| 404 | Brand Not Found | Verify brandId exists |
| 429 | Rate Limited | Wait X-RateLimit-Reset seconds |
| 503 | Service Unavailable | Retry after 5s (real-time inference timeout) |

## Rate Limit Headers (always present)
X-RateLimit-Limit: 100
X-RateLimit-Remaining: {remaining}
X-RateLimit-Reset: {Unix timestamp}

## SDK & Code Generation
The OpenAPI spec at /openapi.json is compatible with:
- OpenAPI Generator (Java, Python, TypeScript, Go)
- Speakeasy SDK generator
- Stainless SDK framework
Generate: npx @openapitools/openapi-generator-cli generate -i https://hordus.ai/openapi.json -g typescript-fetch -o ./sdk