Tornevall Networks

← Back to docs

IRC Log API Guide

IRC Memory Lane - API Guide (current)

This guide documents the current IRC Log API surface.

Base URL

https://tools.tornevall.net/irc/api

Standard flow

  1. Fetch networks:
    • GET /irc/api/networks?source=production
  2. Fetch channels for a network:
    • GET /irc/api/networks/{network_id}/channels?source=production
    • Includes per-channel availability (first_date, last_date, event_count)
  3. Fetch network-level availability interval:
    • GET /irc/api/networks/{network_id}/date-interval?source=production
  4. Fetch per-channel availability intervals explicitly:
    • GET /irc/api/networks/{network_id}/channels/date-intervals?source=production
  5. Search nicknames (incremental, for autocomplete):
    • GET /irc/api/nicknames?q={term}&network_id={id?}&channel_id={id?}&limit=25&source=production
  6. Fetch log rows:
    • GET /irc/api/logs?network_id={id}&channel_id={id}&source=production&limit=100&offset=0

Date interval endpoints

Network interval

  • GET /irc/api/networks/{network_id}/date-interval?source=production

Response:

{
  "success": true,
  "source": "production",
  "network_id": 1,
  "first_date": "1999-04-14 13:55:00",
  "last_date": "1999-04-29 04:11:00",
  "event_count": 123456,
  "total_channels": 42,
  "channels_with_data": 31
}

Channel intervals in network

  • GET /irc/api/networks/{network_id}/channels/date-intervals?source=production

Response contains:

  • channels_with_data
  • channels[] with id, name, first_date, last_date, event_count

source (important)

  • source=production (default)
  • source=sandbox

Use the same source consistently in networks/channels/logs requests.

Nickname search (/irc/api/nicknames)

  • GET /irc/api/nicknames
  • Intended for dynamic/autocomplete lookup (do not fetch all nicks at once).

Query parameters

  • q (string, required in practice; empty returns no rows)
  • network_id (int, optional)
  • channel_id (int, optional)
  • limit (1-100, default 20)
  • source (production|sandbox)

Response shape

{
  "success": true,
  "source": "production",
  "query": "to",
  "count": 2,
  "nicknames": [
    { "nick": "Tompavall", "occurrences": 1204, "last_seen": "2026-07-22 08:10:00" },
    { "nick": "topi", "occurrences": 231, "last_seen": "2004-03-15 12:02:10" }
  ]
}

Log search (/irc/api/logs)

Common query parameters

  • network_id (int)
  • channel_id (int)
  • q (string, free text, also supports +include / -exclude, including quoted phrases)
  • include_terms (string, explicit include terms; space/comma separated)
  • exclude_terms (string, explicit exclude terms; space/comma separated)
  • event_types (string, comma-separated event types, e.g. PRIVMSG,NOTICE,JOIN)
  • nick (string, alias-aware)
  • user / username (string, IRC username; supports * wildcard)
  • host / hostname (string, host or user@host; supports * wildcard)
  • recipient (string)
  • private_only (true|false)
  • date (YYYY-MM-DD)
  • date_from / date_to (YYYY-MM-DD)
  • datetime_from / datetime_to (YYYY-MM-DD HH:MM:SS)
  • limit (1-1000, default 100)
  • offset (>=0, default 0)
  • source (production|sandbox)
  • format (json default, or plain/plaintext/text/txt)

Date precedence

  1. If date is set, that day is used.
  2. Otherwise datetime_from / datetime_to are used when present.
  3. Otherwise date_from / date_to are used.

Examples

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

curl "https://tools.tornevall.net/irc/api/logs?network_id=1&channel_id=1&source=production&q=%2Bflood+-%22received+server%22&include_terms=1999&exclude_terms=bot"

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"

curl -H "Accept: text/plain" "https://tools.tornevall.net/irc/api/logs?network_id=1&channel_id=1&source=production&format=plain&limit=4"

Plain output row format:

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

Authentication

  • The read endpoints above are public.
  • Authorization: Bearer <token> may still be sent when your client already uses token auth.

Privacy and anonymization

  • IRC Memory Lane exposes a public request flow at /irc/privacy-request where users can request nickname protection.
  • Requests are stored and reviewed by admins. Only approved requests affect API output.
  • For each approved request, admins can set:
    • redact_snippets: redact nickname mentions in snippets/text.
    • hide_from_public: hide matching row content for anonymous visitors.
  • In the current implementation, policy enforcement is primarily applied to GET /irc/api/logs.
  • Signed-in Tools users currently see full log content, while anonymous clients receive redacted/hidden content according to policy.
  • When policy matches a row, output may include:
    • privacy_redacted (true|false)
    • privacy_hidden (true|false)
    • privacy_requested_nick (which nickname triggered policy)

Logs response shape

{
  "success": true,
  "source": "production",
  "total": 1234,
  "limit": 100,
  "offset": 0,
  "results": [],
  "nick_profile": null
}

results contains log rows (e.*) plus channel_name. When privacy policy matches, each row may also include privacy_redacted, privacy_hidden, and privacy_requested_nick.

Import Limitations & Data Integrity

Our IRC log import process employs duplicate detection to maintain data quality. While this significantly reduces redundant entries, it may also result in the filtering of legitimate repeated content in the following scenarios:

  • Minute-level precision: Logs recorded with minute-level precision (HH:MM) only cannot distinguish between identical messages occurring at different times within the same minute. Duplicate entries occurring within the same minute may be filtered during import.
  • Spam and flooding: Repeated content from the same user within the same minute may be inadvertently deduplicated.
  • Cross-import duplicates: The same log file imported multiple times is intentionally filtered.

Recommendation: IRC logs recorded with second-level precision (HH:MM:SS) will experience significantly fewer false-positive duplicates and provide more complete event coverage. For archival completeness, consider logs with sub-minute timestamp granularity.

Legacy path note

Older /api/irclog/* examples should be treated as legacy. Use /irc/api/* for new integrations.

Version: 2.3
Updated: 2026-07-23