API Reference

OpenAI-Compatible Proxy

Drop-in replacement. Change baseURL to https://safyan.ai/v1. Every prompt is optimized before reaching the AI.

Request Body

Response

{
  "id": "sfyn-chatcmpl-abc123...",
  "object": "chat.completion",
  "created": 1711756800,
  "model": "claude-haiku-4-5-20251001",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "..." },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 142,
    "completion_tokens": 89,
    "total_tokens": 231
  },
  "safyan": {
    "safyan_primitives": ["PRIME", "LOCK", "BOUND", "SHAPE", "NEGATE"],
    "safyan_mode": "standard",
    "safyan_status": "optimized",
    "safyan_domain": "code",
    "score_before": 22,
    "score_after": 78,
    "score_delta": 56,
    "grade_before": "F",
    "grade_after": "B"
  }
}

Streaming

Set stream: true. Response is SSE in exact OpenAI format:

data: {"id":"sfyn-chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"sfyn-chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},"finish_reason":null}]}

data: [DONE]

Anthropic-Compatible Proxy

Change base_url to https://safyan.ai. Same optimization, Anthropic response format.

Request Body

Response

{
  "id": "sfyn-msg-abc123...",
  "type": "message",
  "role": "assistant",
  "content": [{ "type": "text", "text": "..." }],
  "model": "claude-haiku-4-5-20251001",
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 142, "output_tokens": 89 },
  "safyan": { ... }
}

Models

No authentication required. Returns all available models.

Direct Translation

Translate a human prompt through Safyan's 7 Cures engine. Returns the optimized prompt (not an AI response).

Prompt Scoring

Score a prompt 0-100 against the 7 Cures. Instant, no AI call. Use to show users how to improve.

// Request
{ "text": "help me with code" }

// Response
{
  "total": 17,
  "breakdown": {
    "noise": 5,         // Cure #1: signal clarity (0-15)
    "vagueness": 5,     // Cure #2: specificity (0-15)
    "constraints": 0,   // Cure #3: boundaries (0-15)
    "role": 0,          // Cure #4: expert role (0-15)
    "examples": 0,      // Cure #5: references (0-10)
    "focus": 15,        // Cure #6: single ask (0-15)
    "antipatterns": 0   // Cure #7: what NOT to do (0-15)
  },
  "grade": "F",
  "label": "Vague"
}

Grade scale: A (80+) Expert, B (65+) Strong, C (50+) Average, D (35+) Weak, F (<35) Vague

Response Headers

Every proxy response includes these headers:

Error Codes

All errors follow the format: {"error": {"message": "...", "type": "...", "code": "..."}}

Anthropic format

The Anthropic proxy returns errors in Anthropic's format:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "..."
  }
}

Rate Limits

Rate limits are tracked in-memory with daily reset at midnight UTC. The X-RateLimit-* headers are included in every response.