API Documentation

You need an API key to use these endpoints.

Create your API keys in your account page.

Authentication

You can authenticate your API requests in two ways:

1. Query Parameter

https://aitrafficanalytics.com/api/reports?api_key=YOUR_API_KEY

2. Authorization Header

Authorization: Bearer YOUR_API_KEY

Reports API

List Reports

Get a list of all your reports

GET

/api/reports

Query Parameters

type - Optional. Filter by report type: "brand" or "question"

Example Request

curl -X GET "https://aitrafficanalytics.com/api/reports?type=brand" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "brandReports": [
    {
      "id": 123,
      "brand": "Example Brand",
      "brand_id": 45,
      "created_at": "2025-04-27T14:53:26.000Z",
      "data": { ... }
    }
  ]
}

Get Report

Get a specific report by ID and type

GET

/api/reports/:type/:reportId

URL Parameters

type - Required. Report type: "brand" or "question"
reportId - Required. The ID of the report to retrieve

Example Request

curl -X GET "https://aitrafficanalytics.com/api/reports/brand/123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "id": 123,
  "brand": "Example Brand",
  "brand_id": 45,
  "created_at": "2025-04-27T14:53:26.000Z",
  "data": { ... }
}

Create Brand Report

Create a new brand report

POST

/api/reports/brand

Request Body

brand - Required. The name of the brand to track
questions - Required. Array of questions to ask about the brand

Example Request

curl -X POST "https://aitrafficanalytics.com/api/reports/brand" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "Example Brand",
    "questions": [
      "What are customers saying about Example Brand?",
      "What are the strengths of Example Brand compared to competitors?"
    ]
  }'

Example Response

{
  "id": 124,
  "brand": "Example Brand",
  "brand_id": 45,
  "status": "queued",
  "message": "Brand report has been queued for processing"
}

Create Question Report

Create a new question report

POST

/api/reports/question

Request Body

question - Required. The question to ask LLMs
keywords - Optional. Array of keywords to track in responses

Example Request

curl -X POST "https://aitrafficanalytics.com/api/reports/question" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What are the best practices for prompt engineering?",
    "keywords": ["specificity", "clarity", "examples", "context"]
  }'

Example Response

{
  "id": 89,
  "question": "What are the best practices for prompt engineering?",
  "question_id": 34,
  "status": "queued",
  "message": "Question report has been queued for processing"
}

Delete Report

Delete a specific report

DELETE

/api/reports/:type/:reportId

URL Parameters

type - Required. Report type: "brand" or "question"
reportId - Required. The ID of the report to delete

Example Request

curl -X DELETE "https://aitrafficanalytics.com/api/reports/brand/123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "message": "Brand report deleted successfully"
}

Error Responses

All API errors return the following format:

{
  "error": "Description of the error"
}

Common Error Status Codes

400 - Bad Request: The request is invalid
401 - Unauthorized: Invalid or missing API key
404 - Not Found: The requested resource was not found
500 - Internal Server Error: Something went wrong on our end

Need help with the API? Contact our support team.