Get started with Plith

All product endpoints are authenticated with the x-api-key header. Get a key first, then call any product endpoint.

POST /api/keys is unauthenticated. Both fields are optional — you can create a key with an empty body.

curl -X POST https://api.plith.ai/api/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "name": "My Org"}'

{
  "org_id": "org_abc123",
  "key": "plth_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "prefix": "plth_xxxxxx",
  "message": "Store this key securely — it will not be shown again."
}

Before executing a task, check whether an identical or semantically similar result is already cached. Returns hit, in_progress, or miss. Costs 1 credit.

curl -X POST https://api.plith.ai/api/dedupq/check \
  -H "x-api-key: $PLITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Summarize the Q3 earnings report for Acme Corp",
    "task_id": "task_789",   // optional, your ID for tracing
    "similarity_threshold": 0.92 // optional, default 0.92
  }'

# Hit — skip execution, use cached result
{
  "status": "hit",
  "match": {
    "task_id": "task_456",
    "similarity": 0.97,
    "result": {...},  // your cached output
    "match_type": "semantic",
    "cached_at": "2025-11-01T09:00:00Z"
  },
  "cache_hit": "vector",
  "request_id": "req_abc",
  "credits_used": 1,
  "credits_remaining": 998
}

# Miss — proceed with task execution
{
  "status": "miss",
  "content_hash": "sha256:e3b0c...",
  "message": "No duplicate found. Proceed with task execution.",
  "credits_used": 1,
  "credits_remaining": 999
}

Pass your agent plan as an array of steps. Each step needs a provider, model, and token estimates. Returns a per-step cost breakdown and optimization suggestions. Costs 1 credit.

curl -X POST https://api.plith.ai/api/burnrate/estimate \
  -H "x-api-key: $PLITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plan": [
      {
        "step": 1,
        "provider": "anthropic",
        "model": "claude-sonnet-4-6",
        "estimated_input_tokens": 2000,
        "estimated_output_tokens": 500
      }},
      {
        "step": 2,
        "provider": "openai",
        "model": "gpt-4o-mini",
        "estimated_input_tokens": 500,
        "estimated_output_tokens": 200
      }
    ]
  }'

{
  "estimate": {
    "steps": [
      {"step": 1, "provider": "anthropic", "model": "claude-sonnet-4-6",
       "estimated_input_tokens": 2000, "estimated_output_tokens": 500,
       "cost_usd": 0.00315, "cost_usd_formatted": "$0.003150", "pricing_available": true},
      {"step": 2, "provider": "openai", "model": "gpt-4o-mini", ...}
    ],
    "total_cost_usd": 0.00375,
    "total_cost_usd_formatted": "$0.003750",
    "step_count": 2
  },
  "optimization_suggestions": [
    "Check DedupQ before executing — similar tasks may be cached."
  ],
  "credits_used": 1,
  "credits_remaining": 997
}

Query the cross-org database of known agent failure patterns before executing a task type. Returns pitfalls ranked by severity and report count. Costs 2 credits.

curl -X POST https://api.plith.ai/api/pitfalldb/query \
  -H "x-api-key: $PLITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "code_generation", // required
    "task_description": "Generate a Python function to parse CSV files", // optional, enables semantic search
    "filters": {
      "language": "python", // optional
      "framework": "pandas", // optional
      "provider": "anthropic" // optional
    }
  }'

{
  "pitfalls": [
    {
      "id": "pit_a1b2c3d4",
      "severity": "high",
      "title": "CSV injection via unsanitized cell values",
      "description": "...",
      "frequency": "78% of attempts affected (42 reports)",
      "fix": "Wrap all cell values in quotes, escape embedded quotes with doubling.",
      "fix_confidence": 0.92,
      "tags": ["csv", "injection", "sanitization"],
      "applies_to": {"languages": ["python"]}
    }
  ],
  "total_matching": 3,
  "credits_used": 2,
  "credits_remaining": 995
}