Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Making Your First API Request

Shaf provides a high-throughput REST API v1 designed for developers to embed link shortening, dynamic QR code generation, custom domain routing, and real-time analytics into CI/CD pipelines, web apps, and automation bots.
In this tutorial, you will generate a scoped API key, authenticate HTTP requests, programmatically create an edge short link, and query click telemetry across multiple programming languages.

What You Will Build

Production Deliverable
  • Scoped API Token: Cryptographic bearer token (shaf_live_...) with workspace permissions
  • Programmatic Link: Automated short link created via JSON POST request
  • Multi-Language Automation: Executable snippets in cURL, TypeScript, Python, and Go
  • Analytics Fetching: Programmatic query extracting click counts, top referrers, and geo-data

Prerequisites

  • A Shaf account with access to your organization dashboard.
  • A terminal with curl, or your preferred developer runtime (Node.js 18+, Python 3.9+, or Go 1.20+).

Step-by-Step Instructions

    Generate a Developer API Key

    1. Log into your Shaf Dashboard and select your organization workspace.
    2. In the sidebar, navigate to Settings -> API Keys.
    3. Click Create API Key.
    4. In the dialog, assign a name describing its purpose:
      Deployment Pipeline Automation
    5. Set an expiration period (or select Never Expire for continuous backend services).
    6. Click Generate Token.
    Store Your Secret Token Securely: Shaf cryptographically hashes tokens at rest using SHA-256 and will never display the raw string again. Copy your key immediately and store it in an environment variable or secrets manager.
    Your key will follow the standard Shaf prefix format:
    export SHAF_API_TOKEN="shaf_live_9a7d8f2b3c4e5a6f7b8c9d0e1f2a3b4c"
    Execute the request below to provision an edge link programmatically. Choose your preferred language:
    curl -X POST "https://shaf.app/api/v1/links" \
  -H "Authorization: Bearer $SHAF_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com/meladhani01/shaf",
    "slug": "github-repo",
    "domain": "shaf.is"
  }'

    Inspect the API Response

    Shaf returns a predictable, standardized envelope:
    {
  "code": 0,
  "data": {
    "id": 142,
    "slug": "github-repo",
    "url": "https://github.com/meladhani01/shaf",
    "domain": "shaf.is",
    "shortUrl": "https://shaf.is/github-repo",
    "createdAt": "2026-09-20T21:00:00.000Z",
    "clicks": 0
  }
}
    FieldTypeDescription
    codenumber0 indicates success; non-zero values represent error codes
    data.idnumberUnique persistent database identifier
    data.slugstringThe active path identifier at the edge
    data.domainstringThe authority domain resolving this link
    data.shortUrlstringFully-qualified public URL ready for sharing
    data.clicksnumberReal-time click count (initialized to 0)

    Programmatically Query Analytics

    Fetch aggregated click telemetry for your newly created link:
    curl -X GET "https://shaf.app/api/v1/links/github-repo/analytics?domain=shaf.is" \
  -H "Authorization: Bearer $SHAF_API_TOKEN"
    Example telemetry response:
    {
  "code": 0,
  "data": {
    "totalClicks": 128,
    "uniqueVisitors": 94,
    "topCountries": [
      { "country": "US", "count": 72 },
      { "country": "DE", "count": 28 },
      { "country": "JP", "count": 18 }
    ],
    "topBrowsers": [
      { "browser": "Chrome", "count": 82 },
      { "browser": "Safari", "count": 34 }
    ]
  }
}

Handling API Errors & Status Codes

Shaf follows standard HTTP status codes combined with application error messages:
400 Bad Request — Malformed Input
Occurs if the url field is not a valid HTTP/HTTPS URL, or if the slug contains invalid characters (only lowercase letters, numbers, and hyphens are permitted).
{ "code": 40001, "message": "Invalid URL destination format" }
401 Unauthorized — Authentication Failure
Occurs if the Authorization header is missing, malformed, or contains an expired/revoked API key. Verify that your header uses the format Bearer shaf_live_....
409 Conflict — Duplicate Slug
Occurs if the specified slug is already registered on the requested domain. Ensure your automation generates unique slugs, or omit the slug parameter to let Shaf auto-generate a random 6-character identifier.
429 Too Many Requests — Rate Limiting
Shaf enforces rate limits of 1,200 requests per minute per API key. When exceeded, the API returns HTTP 429 with a Retry-After: <seconds> response header.

🎓 Curriculum Complete! What's Next?

🎉 Congratulations! You are a Shaf Certified Pro!
You have completed all four tutorial levels:
  1. ✅ Quickstart: Created and analyzed your first edge link.
  2. ✅ Custom Domains: Configured DNS CNAME and zero-config SSL.
  3. ✅ Team Workspaces: Scaled collaboration with RBAC permissions.
  4. ✅ REST API: Automated link creation and analytics with code.
Explore Advanced Topics: