Quickstart | Lahjty API

Make your first server-side request, understand the response envelope, and verify your integration safely.

1. Check capabilities

Fetch capabilities during integration and cache them briefly. This prevents old hardcoded dropdown values or prices from drifting away from the live contract.

GET/capabilities

Read live capabilities

This public endpoint is the source of truth for supported values, current credit costs, scopes, and rate limits.

curl --request GET \
  --url https://www.lahjty.com/api/v1/capabilities

Example response

response.json

{
  "object": "capabilities",
  "api_version": "2026-09-03",
  "output_languages": [
    "ar",
    "en"
  ],
  "dialects": [
    "saudi",
    "gulf",
    "emirati",
    "egyptian",
    "classical",
    "levantine",
    "iraqi"
  ],
  "credit_costs": {
    "copy": 2,
    "headline": 2,
    "conversion": 1,
    "image": 5,
    "speech": 5,
    "whatsapp_template": 2
  }
}

2. Generate copy

Every billable POST needs a unique idempotency key. The same key and body can be replayed safely after a timeout without charging twice.

POST/copy-generations

Saudi WhatsApp copy

Returns multiple variants and deterministic required/excluded phrase checks.

curl --request POST \
  --url https://www.lahjty.com/api/v1/copy-generations \
  --header "Authorization: Bearer $LAHJTY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: partner-copy-merchant91-campaign1842" \
  --data '{
  "type": "ad_copy",
  "description": "Weekend offer: 20% off specialty coffee subscriptions",
  "output_language": "ar",
  "market": "SA",
  "dialect": "saudi",
  "platform": "whatsapp",
  "tone": "warm",
  "framework": "aida",
  "audience": "specific",
  "specific_audience": "Young professionals in Riyadh",
  "required_keywords": [
    "قهوة مختصة"
  ],
  "excluded_keywords": [
    "مجاني"
  ],
  "call_to_action": "اطلب الآن",
  "external_customer_id": "merchant-91"
}'

Example response

response.json

{
  "id": "cpy_01jexample",
  "object": "copy_generation",
  "request_id": "req_01jexample",
  "status": "completed",
  "type": "ad_copy",
  "output_language": "ar",
  "market": "SA",
  "dialect": "saudi",
  "dialect_source": "explicit",
  "variants": [
    {
      "index": 1,
      "content": "خصم 20٪ على اشتراك القهوة المختصة لنهاية الأسبوع. اطلب الآن.",
      "keyword_compliance": {
        "passed": true,
        "missing_required": [],
        "matched_excluded": []
      }
    }
  ],
  "usage": {
    "credits_used": 2,
    "balance_after": 498
  }
}

3. Store correlation fields

request_id connects your logs, retries, request lookup, and support cases.
external_id / external_customer_id map a generation to your campaign and merchant records.
usage shows the actual charge and balance after completion.