API Reference

Quickstart

Get started with the Geo Attribution API in minutes. All endpoints return JSON and require authentication via Bearer tokens.

curl -X POST https://geo-attribution.fly.dev/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

Save the access_token from the response and include it in subsequent requests:

curl -X GET https://geo-attribution.fly.dev/api/v1/domains \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" 

Authentication

The API uses JWT Bearer tokens for authentication. Obtain tokens via the login endpoint, then include them in the Authorization header for all authenticated requests.

# Login to get tokens
curl -X POST /api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "password"}'

# Use access token for API calls
curl -X GET /api/v1/domains \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..." 

Access tokens expire after 15 minutes. Use the refresh token to obtain new access tokens without re-authenticating.

Rate Limits

API endpoints are protected by rate limits:

• General API: 60 requests/minute
• Write operations (POST/PUT/DELETE): 30 requests/minute
• Optimization endpoints: 5 requests/minute

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1640995200

Endpoints Overview

The API is organized into functional groups. Each group handles a specific aspect of LLM citation tracking.

Status Codes

The API uses standard HTTP status codes:

• 200 OK - Request successful
• 201 Created - Resource created successfully
• 400 Bad Request - Invalid request format or parameters
• 401 Unauthorized - Missing or invalid authentication
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error

Error responses include detailed information in RFC 9457 format:

{
  "error": "ValidationError",
  "message": "Request validation failed",
  "status": 422,
  "details": [
    {"field": "email", "message": "Invalid email format", "code": "invalid_format"}
  ],
  "instance": "/api/v1/auth/register",
  "requestId": "abc-123"
}