IRC Log API Reference (current)

Base URL: https://tools.tornevall.net/irc/api
Rate limit: typically 60 requests/minute

Authentication

The read endpoints below are public.
You may still send a bearer token if your client already uses token auth:

Authorization: Bearer YOUR_API_TOKEN

Privacy and anonymization

A public request flow exists at /irc/privacy-request.
Requests are manually reviewed by admins and must be approved before policy is applied.
Two policy levels currently exist:
- redact_snippets: redact nickname mentions in snippets/text.
- hide_from_public: hide matching row content for anonymous clients.
Current policy enforcement is primarily tied to GET /irc/api/logs.
Signed-in Tools users currently see full log data, while anonymous clients receive redacted/hidden content according to policy.

Endpoints

`GET /irc/api/networks`

Fetch networks.

Query

Parameter	Type	Required	Description
`source`	string	No	`production` (default) or `sandbox`

Response (example)

{
  "success": true,
  "networks": [
    { "id": 1, "name": "ircnet" }
  ]
}

`GET /irc/api/networks/{networkId}/channels`

Fetch channels for a network.

Path

Parameter	Type	Required
`networkId`	integer	Yes

Query

Parameter	Type	Required	Description
`source`	string	No	`production` (default) or `sandbox`

Response (example)

{
  "success": true,
  "channels": [
    {
      "id": 1,
      "name": "#sweden",
      "first_date": "1999-01-01 00:00:00",
      "last_date": "2026-01-01 00:00:00",
      "event_count": 123456
    }
  ],
  "source": "production"
}

`GET /irc/api/logs`

Fetch log rows with filtering, full-text search, and pagination.

Query

Parameter	Type	Required	Description
`network_id`	integer	No	Filter by network
`channel_id`	integer	No	Filter by channel
`q`	string	No	Free text in message/nick/channel (and target/to_nick where available). Supports `+include` / `-exclude` term syntax, including quoted phrases like `+"very old flood"`
`include_terms`	string	No	Explicit include terms (space/comma separated). All listed terms must match
`exclude_terms`	string	No	Explicit exclude terms (space/comma separated). Listed terms are filtered out
`nick`	string	No	Person/nick filter (alias-aware)
`user` / `username`	string	No	Filter IRC username (`user`). Supports `*` wildcard
`host` / `hostname`	string	No	Filter host (`host` or `user@host`). Supports `*` wildcard
`recipient`	string	No	Exact nick/target/to_nick
`private_only`	boolean	No	Restrict to PM rows
`date`	date	No	Exact day (`YYYY-MM-DD`)
`date_from`	date	No	Date range start
`date_to`	date	No	Date range end
`datetime_from`	datetime	No	Date-time range start (`YYYY-MM-DD HH:MM:SS`)
`datetime_to`	datetime	No	Date-time range end (`YYYY-MM-DD HH:MM:SS`)
`limit`	integer	No	1-1000, default 100
`offset`	integer	No	>=0, default 0
`source`	string	No	`production` (default) or `sandbox`
`include_netsplit`	boolean	No	Include server/net split+merge rows (`false` by default)
`bulk_netsplit`	boolean	No	When `include_netsplit=1`, collapse bursts into one row (`true` by default)
`aggregate`	string	No	`dates` returns unique date count/span instead of normal row list
`format`	string	No	`json` (default) or `plain`/`plaintext`/`text`/`txt` for plain text row output

Date precedence

date
datetime_from / datetime_to
date_from / date_to

Response (example)

{
  "success": true,
  "source": "production",
  "total": 42,
  "limit": 50,
  "offset": 0,
  "results": [
    {
      "id": 123,
      "event_type": "PRIVMSG",
      "occurred_at": "1999-04-14 15:12:00",
      "nick": "TT_",
      "message_text": "Hello",
      "channel_id": 1,
      "channel_name": "#sweden",
      "privacy_redacted": false,
      "privacy_hidden": false
    }
  ],
  "nick_profile": null
}

When policy matches, a row may also include privacy_requested_nick.

Plain text row format

When format=plain (or Accept: text/plain) is used, the response body is plain text and each row is rendered as:

[YYYYMMDD HH:MM:SS] <nick:#channel> <text>

Route aliases in routes/api.php:

GET /api/irclog/logs/json
GET /api/irclog/logs/plaintext

Error format

{
  "success": false,
  "error": "Error message"
}

Common status codes: 200, 422, 429, 500.

Examples

curl "https://tools.tornevall.net/irc/api/networks?source=production"

curl "https://tools.tornevall.net/irc/api/networks/1/channels?source=production"

curl "https://tools.tornevall.net/irc/api/logs?network_id=1&channel_id=1&source=production&q=nu+d%C3%A5&limit=4&offset=0"

curl "https://tools.tornevall.net/irc/api/logs?network_id=1&channel_id=1&source=production&q=%2Bflood+%2B1999+-%22received+server%22&limit=100&offset=0"

curl "https://tools.tornevall.net/irc/api/logs?network_id=1&channel_id=1&source=production&datetime_from=1999-04-14+13:55:00&datetime_to=1999-04-14+16:08:00"

Legacy

/api/irclog/* is legacy and should not be used for new integrations.

Last Updated: 2026-07-23
Version: 2.1

Tornevall Networks