---
title: "HTTP Log API"
description: "The generic log ingestion endpoint behind every Airefs integration. If your platform is not listed, any system that can POST JSON can use it directly."
---

> Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP Log API

`POST [https://api.getairefs.com/v1/logs/http](https://api.getairefs.com/v1/logs/http)` accepts a single JSON object, a JSON array, or NDJSON — up to 10,000 records and 8 MB per request, gzip-compressed bodies included. Send all traffic: Airefs classifies bots versus humans and drops assets, non-HTML responses, and errors server-side. This powers [AI Impressions](/docs/impressions/); for client-side [Clicks](/docs/clicks/), also add the tracking script from **Site Settings → Tracking Script**.

Authenticate with the Access Token from **Site Settings → Access Token**, sent as `X-API-Key`, `Authorization: Bearer`, Basic auth password, or a `?token=` query parameter.

## Record format

| Field | Required | Description |
| --- | --- | --- |
| `event_id` | Yes | Stable request identifier; reuse the same value when retrying a record |
| `timestamp` | Yes | ISO 8601 or epoch milliseconds; required so retried records keep stable sessions |
| `status_code` | No  | HTTP response status; without it error responses cannot be filtered |
| `request_method` | No  | HTTP method, e.g. GET |
| `request_path` | Yes | Path, or a full URL (which makes hostname optional) |
| `query_string` | No  | Query string without the leading ? |
| `hostname` | Yes\\* | Host that served the request; required unless request\\_path is a full URL |
| `content_type` | No  | Response content type, e.g. text/html |
| `client_ip` | No  | Client IP address |
| `user_agent` | No  | Client user agent, needed for AI crawler detection |
| `referrer` | No  | Request referrer |
| `country_code` | No  | ISO 3166-1 alpha-2 country code |
| `event_client` | No  | Provenance string, e.g. my-custom-forwarder@1.0.0 |

Common alternate key names are accepted (for example `method`, `status`, `url`, `referer`, `ip`, `country`), so most existing log pipelines can point at the endpoint without renaming fields. The exhaustive alias list, batch limits, and response schemas are in the request below and mirrored in your dashboard’s integration guide.

## Example

```bash
curl -X POST https://api.getairefs.com/v1/logs/http \
  -H "X-API-Key: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "req-8f2a91c4",
    "timestamp": "2026-07-16T12:00:00Z",
    "status_code": 200,
    "request_method": "GET",
    "request_path": "/blog/my-article",
    "hostname": "www.example.com",
    "content_type": "text/html",
    "client_ip": "203.0.113.1",
    "user_agent": "PerplexityBot/1.0",
    "referrer": "https://www.perplexity.ai/",
    "event_client": "my-custom-forwarder@1.0.0"
  }'
```

## Ingest summaries

Every response reports what happened to the batch — a misconfigured field shows up as an `unparsed` count on the first request instead of silently missing data:

```json
{
  "success": true,
  "received": 120,
  "accepted": 34,
  "dropped": { "asset_path": 71, "status": 9, "excluded_path": 4, "unparsed": 2 }
}
```

A large `asset_path` count on real traffic is expected: send everything and let the filter work.

## Verification

Outside dry-run mode, a successful response means Airefs stored every accepted record and reports why the rest were dropped. For a one-off test before going live, POST a sample record with `?dry_run=1` appended to the endpoint URL: Airefs returns a per-record verdict, including the bot classification it detected, without storing anything.

`401` means the token is wrong. `200` with everything in `dropped.unparsed` means the field names do not match: check the record format above or run a `?dry_run=1` request to see per-record verdicts. Need help? Email [support@getairefs.com](mailto:support@getairefs.com).

Source: /docs/integrations/http-api/