API Reference

Overview

The Tathor API is a RESTful API that provides programmatic access to business intelligence and competitor analysis features. All requests must be made over HTTPS to the base URL https://app.tathor.com/api/v1.

All responses are returned in JSON format. The API follows REST conventions, uses standard HTTP status codes, and requires authentication via Bearer tokens in the Authorization header.

Authentication

All API requests require authentication using a Bearer token. Include your API key in the Authorization header of every request.

Getting Your API Key

API keys can be generated from your account settings in the Tathor dashboard. Each key has full access to your account's resources.

Using Your API Key

Include your API key in the Authorization header using the Bearer authentication scheme:

Authorization: Bearer YOUR_API_KEY

Endpoints

The Tathor API provides the following endpoints for managing analyses, profiles, and webhooks:

Analyze Endpoint

Submit a business or website URL for analysis. The endpoint returns immediately with a job ID, and analysis runs asynchronously. Use webhooks or poll the profiles endpoint to check completion status.

Endpoint

POST https://app.tathor.com/api/v1/analyze

Request Body

Example Request

const response = await fetch('https://app.tathor.com/api/v1/analyze', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    url: 'https://example.com',
    analysis_type: 'business_intelligence'
  })
});

const data = await response.json();
console.log(data);

Response

Returns a 201 Created status code with the analysis job details:

{
  "id": "analysis_abc123",
  "status": "processing",
  "url": "https://example.com",
  "analysis_type": "business_intelligence",
  "created_at": "2024-01-26T10:00:00Z",
  "estimated_completion": "2024-01-26T10:10:00Z"
}

Profiles Endpoint

Retrieve competitor profiles generated from completed analyses. Profiles contain comprehensive business intelligence including customer insights, pain points, and competitive positioning.

List Profiles

GET https://app.tathor.com/api/v1/profiles

Query Parameters

Example Request

GET https://app.tathor.com/api/v1/profiles?page=1&limit=20&status=completed

Example Response

{
  "data": [
    {
      "id": "profile_xyz789",
      "business_name": "Example Corp",
      "url": "https://example.com",
      "status": "completed",
      "created_at": "2024-01-26T10:00:00Z",
      "updated_at": "2024-01-26T10:10:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "total_pages": 3
  }
}

Get Profile by ID

GET https://app.tathor.com/api/v1/profiles/:id

Retrieve detailed information for a specific profile, including all analysis data.

Example Response

{
  "id": "profile_xyz789",
  "business_name": "Example Corp",
  "url": "https://example.com",
  "status": "completed",
  "data": {
    "scorecard": {
      "overall_score": 85,
      "categories": { ... }
    },
    "pain_points": [
      {
        "title": "Customer Service Issues",
        "severity": "high",
        "frequency": 0.42
      }
    ],
    "solutions": [
      {
        "title": "24/7 Support",
        "impact": "high",
        "feasibility": "medium"
      }
    ],
    "revenue_impact": {
      "estimated_annual": 2500000,
      "currency": "USD"
    }
  },
  "created_at": "2024-01-26T10:00:00Z",
  "updated_at": "2024-01-26T10:10:00Z"
}

Webhooks

Webhooks allow you to receive real-time notifications when analysis jobs complete or encounter errors. Configure webhook endpoints to automatically process events without polling.

Create Webhook

POST https://app.tathor.com/api/v1/webhooks

Request Body

Example Request

POST https://app.tathor.com/api/v1/webhooks
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "url": "https://your-app.com/webhook",
  "events": ["analysis.completed", "analysis.failed"],
  "secret": "your_webhook_secret"
}

Example Response

{
  "id": "webhook_123",
  "url": "https://your-app.com/webhook",
  "events": ["analysis.completed", "analysis.failed"],
  "created_at": "2024-01-26T10:00:00Z",
  "active": true
}

List Webhooks

GET https://app.tathor.com/api/v1/webhooks

Retrieve all registered webhook endpoints for your account.

Webhook Payload

When an event occurs, Tathor sends a POST request to your webhook URL with the following payload structure:

{
  "event": "analysis.completed",
  "data": {
    "id": "analysis_abc123",
    "status": "completed",
    "url": "https://example.com",
    "profile_id": "profile_xyz789"
  },
  "timestamp": "2024-01-26T10:10:00Z",
  "signature": "sha256=..."
}

Error Handling

The API uses standard HTTP status codes to indicate success or failure. Error responses include a JSON object with details about what went wrong.

HTTP Status Codes

Error Response Format

All error responses follow this structure:

{
  "error": {
    "code": "invalid_request",
    "message": "The URL provided is invalid",
    "details": {
      "field": "url",
      "reason": "Must be a valid HTTP or HTTPS URL"
    }
  }
}

Rate Limits

API requests are rate-limited to ensure fair usage. Rate limits vary by plan tier. When exceeded, you'll receive a 429 status code with rate limit information in response headers:

• X-RateLimit-Limit - Total requests allowed per window
• X-RateLimit-Remaining - Requests remaining in current window
• X-RateLimit-Reset - Unix timestamp when the limit resets