API Reference

REST API endpoints for prompt adaptation, model discovery, and account management. All endpoints accept and return JSON.

POST /api/adapt

Adapt a system prompt for a specific model and task type.

Request Body

{
  "prompt": "You are a helpful assistant...",
  "model": "claude-sonnet-4-20250514",
  "task": "chat",           // optional
  "user_prompt": "Hello"    // optional
}

Response

{
  "adapted": "...",
  "original": "...",
  "changes": [
    {
      "type": "modify",
      "description": "Added XML structure tags",
      "before": "...",
      "after": "...",
      "reason": "Claude performs better with XML-delimited sections"
    }
  ],
  "model": { "id": "...", "name": "...", "provider": "..." },
  "metadata": {
    "duration_ms": 230,
    "rules_applied": 4,
    "task": "chat"
  }
}

SDK Usage

import refrase

result = refrase.adapt(
    prompt="You are a helpful assistant...",
    model="claude-sonnet-4-20250514",
    task="chat",
    user_prompt="Hello",
)

print(result.adapted)
print(result.changes)

GET /api/models

List all supported models with their capabilities and optimization rules.

Response

[
  {
    "id": "claude-sonnet-4-20250514",
    "name": "Claude Sonnet 4",
    "provider": "anthropic",
    "capabilities": ["xml_tags", "thinking", "tool_use"]
  },
  ...
]

SDK Usage

import refrase

models = refrase.list_models()
for model in models:
    print(f"{model['name']} ({model['provider']})")

GET /api/models/:id

Get details for a single model, including its full rule set.

Response

{
  "id": "claude-sonnet-4-20250514",
  "name": "Claude Sonnet 4",
  "provider": "anthropic",
  "capabilities": ["xml_tags", "thinking", "tool_use"],
  "rules": [
    {
      "id": "xml-structure",
      "description": "Wrap sections in XML tags",
      "priority": 1
    }
  ]
}

GET /api/benchmarks

Retrieve benchmark data comparing model performance with and without prompt optimization.

POST /api/share

Create a shareable link for a prompt adaptation result.

Request Body

{
  "prompt": "...",
  "adapted": "...",
  "model": "claude-sonnet-4-20250514",
  "changes": [...]
}

Response

{
  "id": "abc123",
  "url": "https://refrase.cc/s/abc123"
}

SDK Usage

import refrase
import requests

# After adapting a prompt
result = refrase.adapt(
    prompt="Your system prompt...",
    model="claude-sonnet-4-20250514",
)

# Share the result
response = requests.post(
    "https://api.refrase.cc/v1/share",
    json={
        "prompt": result.original,
        "adapted": result.adapted,
        "model": "claude-sonnet-4-20250514",
        "changes": [c.__dict__ for c in result.changes],
    },
)
print(response.json()["url"])

GET /api/share/:id

Retrieve a previously shared prompt adaptation.

Authenticated Endpoints

The following endpoints require authentication via a Bearer token in the Authorization header.

Authentication Example

import requests

headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Content-Type": "application/json",
}

# Get usage stats
response = requests.get(
    "https://api.refrase.cc/v1/usage",
    headers=headers,
)
print(response.json())