Terse API

Optimize a prompt or text string. Returns the compressed version plus token stats. This is the core endpoint — call it before every LLM API call to reduce costs.

Request body

Response

{
  "original": "Can you please help me understand how the auth middleware works?",
  "optimized": "Explain the auth middleware.",
  "tokens_original": 16,
  "tokens_optimized": 6,
  "tokens_saved": 10,
  "reduction_pct": 62,
  "techniques": ["phrase_optimization", "filler_removal"],
  "mode": "normal"
}

Example

Scan source code to detect LLM API call sites. Returns a list of findings with line numbers, types, and specific recommendations for each call site. Use this during development to audit where tokens are being spent.

Request body

Detected call site types

• anthropic_messages — client.messages.create() calls
• openai_chat — client.chat.completions.create() calls
• google_gemini — Gemini API calls
• anthropic_http / openai_http — raw HTTP fetch to API endpoints
• system_prompt / user_prompt — prompt variable assignments
• messages_array — "messages": array construction sites

Response

{
  "findings": [
    {
      "line": 12,
      "type": "anthropic_messages",
      "preview": "const response = await client.messages.create({",
      "estimated_tokens": 85,
      "potential_savings_pct": 35,
      "recommendation": "Wrap this call with Terse to auto-optimize the 'content' field before it reaches the API."
    },
    {
      "line": 34,
      "type": "system_prompt",
      "preview": "const system_prompt = `You are a helpful assistant...",
      "estimated_tokens": 140,
      "potential_savings_pct": 45,
      "recommendation": "System prompts are ideal candidates for aggressive mode (removes filler, compresses markdown)."
    }
  ],
  "total_findings": 2,
  "estimated_monthly_savings_tokens": 78540,
  "recommendation": "Found 2 optimization opportunities. Wrapping these calls with Terse could save ~78540 tokens/month."
}

Example — scan a whole file

const fs = require('fs');
const code = fs.readFileSync('./src/agent.js', 'utf8');

const res = await fetch('https://www.terseai.org/api/v1/scan', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.TERSE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ code, language: 'javascript' }),
});

const result = await res.json();
console.log(`Found ${result.total_findings} LLM calls`);
result.findings.forEach(f => {
  console.log(`  Line ${f.line} [${f.type}]: ${f.recommendation}`);
});

Create a new developer API key. Requires a valid Clerk session token (sign in at terseai.org first). The full key is only returned once — store it securely.

Headers

Pass your Clerk session JWT as Authorization: Bearer <clerk_token> (not a tsk_ key — this endpoint uses your account login token).

Request body

Response

{
  "key": "tsk_AbCdEfGhIjKlMnOpQrStUvWxYz12345",
  "prefix": "tsk_AbCdEfGh...",
  "label": "My vibe project",
  "id": "uuid-here",
  "created_at": "2026-05-15T12:00:00.000Z"
}

List all API keys for your account. Returns metadata only — full key values are never returned after creation.

Response

{
  "keys": [
    {
      "id": "uuid",
      "key_prefix": "tsk_AbCdEfGh...",
      "label": "My vibe project",
      "is_active": 1,
      "requests_total": 1247,
      "tokens_optimized": 892430,
      "last_used_at": "2026-05-15T11:22:00",
      "created_at": "2026-05-01T09:00:00"
    }
  ]
}

Revoke an API key. Requests made with the revoked key will immediately return 401. Use the key ID from GET /keys.

Response

{ "ok": true }

List published vibe coding projects from the platform. No auth required. Featured projects appear first, then sorted by upvotes.

Query parameters

Response

{
  "projects": [
    {
      "id": "uuid",
      "name": "ClaudeFlow",
      "description": "Multi-agent workflow builder...",
      "github_url": "https://github.com/...",
      "website_url": "https://claudeflow.dev",
      "tags": ["Node.js", "Agents"],
      "tokens_saved_monthly": 38000,
      "cost_saved_monthly_cents": 570,
      "upvotes": 247,
      "is_featured": true,
      "submitted_at": "2026-05-10T08:00:00"
    }
  ]
}

Submit your vibe coding project to the showcase. Accepts either a Clerk session token or a developer API key (tsk_...). Projects are reviewed before being featured.

Request body

Response

{ "ok": true, "id": "uuid" }

Submit via API key (programmatic)

const res = await fetch('https://www.terseai.org/api/v1/projects', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.TERSE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'My Vibe Project',
    description: 'An AI coding tool that uses Terse to cut API costs by 40%.',
    github_url: 'https://github.com/you/myproject',
    tags: ['TypeScript', 'Agents'],
    tokens_saved_monthly: 50000,
  }),
});

Upvote a project. No auth required. Pass the project ID from GET /projects.

Response

{ "ok": true }