WEIR External API

External API for third-party integrations. Access licenses and mentions you have permission to view, manage webhooks, and bookmark content.

Authentication Overview

This API uses Bearer tokens for authentication. There are two types of endpoints:

🔓 Public Endpoints (No Authentication)

  • GET /health - Health check
  • GET /metadata - Public license catalog (rate-limited)
  • GET /.well-known/weir - Discovery endpoint
  • POST /auth/token - Exchange API key for access token
  • POST /auth/token/refresh - Refresh access token
  • POST /token/info - Introspect token validity

🔑 Authenticated Endpoints

All other endpoints require a valid External API Token obtained by exchanging your API key and secret.

How to Authenticate

Step 1: Create API Key

Generate an API key in WEIR Developer Settings at https://weir.ai/developers

Step 2: Obtain Access Token

curl -X POST https://wapi.weir.ai/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "YOUR_API_KEY", "api_secret": "YOUR_API_SECRET"}'

Step 3: Use Token in Requests

curl https://wapi.weir.ai/licenses \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Scopes

Tokens are issued with specific scopes based on your API key permissions:

  • license:read - View licenses
  • mention:read - View mentions
  • webhook:manage - Create/update/delete webhooks

Rate Limits

Rate limits are based on your plan tier. Headers included in responses:

  • X-RateLimit-Limit - Maximum requests per window
  • X-RateLimit-Remaining - Requests remaining
  • X-RateLimit-Reset - Unix timestamp when window resets

Changelog

v3.1.0 (December 2024) - Improved Rate Limiting & Security

  • Improved: Magic link rate limiting now only counts unused OTP requests (better UX for retries)
  • Improved: Magic links are automatically deleted after successful verification (security enhancement)
  • Improved: Generic error responses for certain authentication failures (prevents account enumeration)
  • Note: Rate limit of 3 unused magic links per hour per email remains unchanged

v3.0.0 (December 2024) - BREAKING CHANGE: Passwordless Authentication

  • Removed: Password-based authentication endpoints
  • Modified: POST /register now passwordless (no password field)
  • Modified: POST /magic-link/verify accepts { email, otp } or { token }
  • New: 6-digit OTP sent with magic link emails
  • New: OTP autofill support on iOS/Android
  • See migration guide: https://weir.ai/developers/migration-v3

v2.15.0 (December 2024)

  • Removed internal-only endpoints from external API spec
  • Added POST /auth/token documentation
  • Added POST /token/info for token introspection
  • Added POST /webhooks/{id}/test for webhook testing
  • Cleaned up unused schemas

Endpoints

/health

  • GET: Health check

Response:

{
  "status": "healthy",
  "api_type": "external",
  "version": "3.1.0",
  "timestamp": "2024-12-22T10:30:00Z"
}

/auth/token

  • POST: Exchange API key for access token

Request Body:

{
  "api_key": "wapi_abc123...",
  "api_secret": "wapi_secret_xyz789..."
}

Response:

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "wrtx_abc123xyz789...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scopes": ["license:read", "mention:read"]
  }
}

/auth/token/refresh

  • POST: Refresh access token

Request Body:

{
  "refresh_token": "wrtx_abc123xyz789..."
}

Response:

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600
  }
}

/token/info

  • POST: Introspect token validity

Request Body:

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Response:

{
  "success": true,
  "data": {
    "active": true,
    "token_type": "external",
    "scopes": ["license:read", "mention:read"],
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "issued_at": "2024-12-15T10:00:00Z",
    "expires_at": "2024-12-15T11:00:00Z",
    "expires_in": 2400,
    "revoked": false
  }
}

/licenses

  • GET: List accessible licenses

Response:

{
  "data": [ /* array of licenses */ ],
  "pagination": { "page": 1, "per_page": 20, "total": 100, "total_pages": 5 }
}

/licenses/{id}

  • GET: Get license details

Response:

{ /* License data */ }

/licenses/{id}/mentions

  • GET: Get license mentions

Response:

{
  "data": [ /* array of mentions */ ],
  "pagination": { "page": 1, "per_page": 20, "total": 30, "total_pages": 2 }
}

/webhooks

  • GET: List webhooks

Response:

{
  "data": [ /* array of webhooks */ ]
}

/bookmarks

  • GET: List bookmarks

Response:

{
  "data": [ /* array of bookmarks */ ],
  "pagination": { "page": 1, "per_page": 20, "total": 10, "total_pages": 1 }
}

/metadata

  • GET: Public license catalog

Response:

{
  "metadata_version": "1.0",
  "total_count": 100,
  "returned_count": 10,
  "licenses": [ /* array of metadata licenses */ ]
}

/.well-known/weir

  • GET: Well-known discovery endpoint

Response:

{
  "weir_metadata": "https://weir.ai/metadata",
  "metadata_version": "1.0",
  "powered_by": "WEIR",
  "public": true,
  "documentation": "https://weir.ai/developers"
}

Contact

This document summarizes the main functional aspects of the WEIR External API v2. It provides authentication methods, endpoint descriptions, request/response structure, and notes on rate limiting, scopes, and recent changelogs.