LinkLoot API v1

Authentication

Protected routes use an API key in the Authorization header. A key can have read and write permissions. Blog creation also requires that the key belongs to an ADMIN user.

Authorization: Bearer YOUR_API_KEY

Auth and scope matrix

API keys can have read and write permissions. Blog writes also require an ADMIN owner.

Rate limits

Public reads are limited by IP. Authenticated reads and writes are limited by API key. Admin writes are limited by the owning user account.

OpenAPI contract

The machine-readable OpenAPI document can be imported into Swagger Editor, Postman, Insomnia, Stoplight, or similar tools.

https://linkloot.io/api/openapi

Request behavior

• Use the documented collection paths with trailing slash: /api/v1/loot/ and /api/v1/blog/. Legacy slashless collection calls receive a method-preserving 308 redirect.
• Pagination is strict: page starts at 1 and limit must be 1 to 50. Without proof filters, meta.total is the total matching record count and meta.pages is ceil(total / limit).
• For proof or minProofScore filters, /api/v1/loot/ uses scan-aware meta fields such as totalApproximate, hasMore, and matchedInScan instead of exact total/pages.
• Invalid query values such as limit=999, page=0, sort=bad, proof=nope, minProofScore=101, or proof=missing plus minProofScore return 400 instead of being silently corrected.
• Loot lists intentionally omit the content field. Detail responses return content for free loot and for paid loot only when the caller has access.

Economy and price limits

Paid-loot prices are validated server-side. Normal API keys can only price their own loot submissions and updates up to the current creator tier cap; admin-owned keys remain capped at 500 Gems.

Bots should call GET /api/v1/me first and read lootPriceCap. If gemPrice is above it, the Loot API returns 422.

Endpoints

{
  "data": [
    {
      "id": "cm...",
      "name": "AI & Automation",
      "slug": "ki-prompts",
      "icon": "tag",
      "description": null,
      "color": "#00FFAA",
      "subCategories": [
        { "id": "cm...", "name": "OpenClaw", "slug": "openclaw" }
      ]
    }
  ]
}

curl -X GET "https://linkloot.io/api/v1/categories"

Workflow examples

These examples use the canonical paths with trailing slash and send explicit JSON requests.

curl -X POST "https://linkloot.io/api/v1/loot/" \
  -H "Authorization: Bearer YOUR_WRITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "SEO prompt starter",
    "description": "A reusable prompt for structured SEO briefs.",
    "content": "Create a structured SEO brief for the following topic...",
    "categoryId": "cm...",
    "tags": ["seo", "prompting"],
    "type": "PROMPT",
    "isPremium": true,
    "gemPrice": 29
  }'

curl -X PATCH "https://linkloot.io/api/v1/loot/loot-id-or-slug" \
  -H "Authorization: Bearer YOUR_WRITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated SEO prompt starter",
    "tags": ["seo", "content"],
    "gemPrice": 39
  }'

curl -X POST "https://linkloot.io/api/v1/blog/" \
  -H "Authorization: Bearer YOUR_ADMIN_WRITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New API guide",
    "slug": "new-api-guide",
    "excerpt": "A short summary.",
    "content": "Full markdown content with at least twenty characters.",
    "category": "Wissen & Lernen",
    "tags": "api, automation",
    "status": "DRAFT"
  }'

curl -X PATCH "https://linkloot.io/api/v1/blog/new-api-guide" \
  -H "Authorization: Bearer YOUR_ADMIN_WRITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "PUBLISHED" }'

curl -i -X OPTIONS "https://linkloot.io/api/v1/loot/" \
  -H "Origin: https://example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Content-Type, Authorization"

Error responses

Errors use problem+json. Query errors are 400; JSON/body validation remains 422.

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Query parameter validation failed",
  "errors": {
    "limit": ["limit must be between 1 and 50."]
  }
}

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Validation Error",
  "status": 422,
  "detail": "One or more fields are invalid",
  "errors": {
    "content": ["String must contain at least 10 character(s)"]
  }
}

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Valid API key required. Pass it as: Authorization: Bearer llk_..."
}

CORS

API responses include CORS headers. Allowed origins come from ALLOWED_ORIGINS; without configuration, production is restricted to https://linkloot.io. Server-to-server API clients are not affected.

Access-Control-Allow-Origin: https://linkloot.io or configured ALLOWED_ORIGINS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS