Documentation
Txtlog offers a simple online logfile. The REST API can be used to create and manage logs.
Setting up a
self hosted version is described on a separate page.
To start, create a new log. Each log can contain zero or more rows.
The return value are for successful actions, the error table at the bottom lists the potential errors which can occur.
Insert new logs
Send a POST request to create a new log row. Data is inserted asynchronously in batches, usually within a few seconds.
Send unformatted text or JSON. It's possible to insert up to 10.000 rows at once, see the examples below.
All fields are optional and data is automatically truncated if a row is too long.
Domain
https://in.txtlog.net
Return value
HTTP status code 202 (Accepted).
Number of inserted rows.
{
"status": "accepted",
"inserts": 1
}
Header: authorization
Required, use an insert or admin token to insert new rows.
Header: X-Metadata
Optional, set to false to disable automatic metadata.
If the input is JSON, the log is extended with a metadata field txtlog_metadata, if it does not exist.
The metadata contains a field origin_ip which is filled with the IP address which inserted the log.
If the input JSON contains a field ip the metadata includes a GEO IP check on this address and sets the fields ip_country, ip_provider and ip_tor (true if the IP address is a TOR exit node).
If the input JSON contains a field browser the metadata is extended with the fields browser_name, browser_version and browser_os.
date
Custom event date, use this date to specify the exact time an event happened. This value can be at most one day in the past.
The date column must have exactly this format: yyyy-mm-dd hh:mm:ss or yyyy-mm-dd hh:mm:ss.sss to indicate milliseconds.
Indicators, such as Z or T are ignored, the date field does not handle timezones, use your local time when inserting logs. Some valid dates:
2024-02-17 09:30:00
2024-01-28 22:01:13.810
2024-01-28T22:01:13.810Z
ip
If the field ip contains a valid IP address, a Geo IP check is performed. The log message is extended with the IP country, provider and a boolean indicating if the IP is a TOR address.
browser
If the field browser contains a valid User Agent string, this value is parsed and the log is extended with browser metadata.
rows
Multiple rows can be provided in one request.
Use a JSON array to specify multiple rows, see the example below.
Add a new row using cURL.
curl https://in.txtlog.net/api/log \
-H "Authorization: ncSZX8Qz8Kqzj9Kbk4F6HR22xAF3" \
-d '{"date":"2024-11-03 11:13:01","msg":"login test","ip":"127.0.0.1","browser":"Mozilla/5.0 (X11; Linux x86_64; rv:128.0) Gecko/20100101 Firefox/128.0"}'
It is faster to insert multiple rows at once. Use the rows element to specify multiple rows.
curl https://in.txtlog.net/api/log \
-H "Authorization: ncSZX8Qz8Kqzj9Kbk4F6HR22xAF3" \
-d '{"rows":[{"action":"rdplogin","user":"admin"},{"action":"sshlogout","ip":"127.0.0.1"}]}'
using System;
using System.Net.Http;
class Txtlog {
public async System.Threading.Tasks.Task Send() {
// Add a new row to a log, set these three variables
string logUrl = "https://in.txtlog.net/api/log";
string authorization = "ncSZX8Qz8Kqzj9Kbk4F6HR22xAF3";
var data = new System.Collections.Generic.Dictionary<string, string>() { { "user", "1234" }, { "trace_id", Guid.NewGuid().ToString() } };
using (var client = new HttpClient()) {
client.DefaultRequestHeaders.TryAddWithoutValidation("Authorization", authorization);
var jsonSerializer = new System.Web.Script.Serialization.JavaScriptSerializer();
HttpResponseMessage response = await client.PostAsync(logUrl, new StringContent(jsonSerializer.Serialize(data)));
string result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
}
class Program {
static void Main(string[] args) {
Txtlog t = new Txtlog();
t.Send().Wait();
}
}
// Add a new row to a log, set these variables
authorization = 'ncSZX8Qz8Kqzj9Kbk4F6HR22xAF3';
data = { "user": 456, "login": true};
const https = require('node:https');
const options = {
hostname: 'in.txtlog.net',
path: '/api/log',
method: 'POST',
headers: {
'Authorization': authorization,
}
};
const req = https.request(options, (res) => {
res.on('data', (result) => {
process.stdout.write(result);
});
});
req.write(JSON.stringify(data));
req.end();
<?php
// Add a new row to a log, set these variables
$authorization = 'ncSZX8Qz8Kqzj9Kbk4F6HR22xAF3';
$data = ['user'=>123, 'ip'=>'127.0.0.1'];
$logUrl = 'https://in.txtlog.net/api/log';
$ch = curl_init($logUrl);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
if(strlen($authorization) > 0) {
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: $authorization"]);
}
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if($result === false || $status != 202) {
// Handle errors
}
curl_close($ch);
print_r($result);
import requests
# Add a new row to a log, set these three variables
url = "https://in.txtlog.net/api/log"
data = {'user': 123, 'type': 'login'}
authorization = "ncSZX8Qz8Kqzj9Kbk4F6HR22xAF3"
headers = {
'Authorization': authorization
}
result = requests.post(url, headers=headers, json=data)
print(result.text)
Create new log
Create a new log, all parameters are optional.
Return value
HTTP status code 201 (Created).
JSON object containing several tokens and an URL to view the log.
- admin: token to insert, view, delete logs or to generate new tokens
- insert: token only valid for inserting rows
- view: URL for viewing the log
{
"status": "created",
"admin": "XEpzD4p6zyJW795WpKsthUXurCsQ",
"insert": "ncSZX8Qz8Kqzj9Kbk4F6HR22xAF3",
"view": "https://txtlog.net/api/log/1KxAkipMQDsShjzua8xm1ncdNfsY3"
}
name
A custom name for the log, this name is displayed when viewing the log.
retention
Determines when rows are deleted from a log, e.g. a retention of 15 means rows older than 15 days are automatically deleted.
Provide a number between 1 and 365
Default value: 30
username
Optional username, when setting a username,
login with this username and password instead of remembering the URLs.
password
Optional password (max. 70 characters), required when setting a username.
The following example creates a new log
curl -X POST https://txtlog.net/api/log
The next example creates a new log with name firstlog and a retention of 7 days, e.g. all logs older than 7 days are automatically removed. Also sets a username user1 and a password hunter2
curl -d 'name=firstlog&retention=7&username=test1&password=hunter2' https://txtlog.net/api/log
Update log
Sent a PATCH request to update an existing log.
Return value
HTTP status code 200 (OK).
JSON object with the result.
{
"status": "updated",
"usermsg": "Password successfully updated"
}
Header: authorization
Required, use an admin token.
name
A custom name for the log, this name is displayed when viewing the log.
Provide an empty string "" to clear the name.
username
Username, can only be set when the log has no username yet, cannot be changed.
password
New password, used for login.
retention
Update the log retention. Note: the updated retention is set for new rows, existing rows will not be changed.
The following example clears the name of the log and updates the password.
curl -H "Authorization: XEpzD4p6zyJW795WpKsthUXurCsQ" \
-d 'name=""&username=test2&password=hunter3' \
-X PATCH \
https://txtlog.net/api/log
Delete log
Sent a DELETE request to delete an existing log.
Return value
HTTP status code 200 (OK).
Status message indicating deleted
{
"status": "deleted"
}
Header: authorization
Required, use an admin token
Delete a log by sending a DELETE request.
curl -H "Authorization: XEpzD4p6zyJW795WpKsthUXurCsQ" \
-X DELETE \
https://txtlog.net/api/log
Get logs
Return value
HTTP status code 200 (OK).
The result contains both log metadata and log rows.
Without parameters, max. 250 rows are returned in the output.
Header: authorization
Use a view or admin token to view the log.
The authorization code can also be set in the URL, e.g. https://txtlog.net/api/log/1KxAkipMQDsShjzua8xm1ncdNfsY3
limit
Return this many rows, can be any number between 1 and 5000.
date
Search logs on or before the given date. Provide the date as yyyy-mm-dd with an optional time.
Some valid search dates:
2024-02-10
2024-02-10 14:41:19
2024-02-10 14:41:19.307
data
Case insensitive text search, for searching any text in the row, like an IP address, UUID, unique value, etc.
The search parameter does not support partial matches or wildcards.
Searching is done using a bloom filter, if you get the error message "Search timeout, showing partial results." try a filter with less common search terms.
type
Set to html or json to force the output format
The return value consists of log metadata and a list of rows.
base_url
canonical url for the log
url
log url including search parameters
prev
link to the page with newer results
next
link to the page with older results
fixed_search
fixed search string for public dashboards
create
UTC log creation date and time
modify
UTC log date and time of the last metadata mutation
name
custom name provided when creating or patching the log
authorization
yes if the log is password protected
retention
number of days log rows are kept
total_rows
number of rows in this log (cached)
rows
element containing the log rows
Get 2 rows from a log.
curl https://txtlog.net/api/log/1KxAkipMQDsShjzua8xm1ncdNfsY3?limit=2
Login
Login with a username and password. A username can be set when creating or updating a log.
Return value
HTTP status code 200 (Ok).
JSON object containing several tokens and an URL to view the log, see creating a new log for the token types.
{
"account": "Anonymous",
"username": "test1",
"userhash": "1b4f0e9851971998",
"admin": "XEpzD4p6zyJW795WpKsthUXurCsQ",
"insert": "ncSZX8Qz8Kqzj9Kbk4F6HR22xAF3",
"view": "https://txtlog.net/api/log/1KxAkipMQDsShjzua8xm1ncdNfsY3"
}
The following POST parameters are required.
username
Username, set when creating or updating the log. The username can be set at any time but it cannot be changed.
password
Password, set when creating or updating the log.
Login from the command line, returning an admin, insert and view token.
curl -d 'username=test1&password=hunter2' https://txtlog.net/api/login
List tokens
List all tokens, max 100 different tokens per log can be created.
Tokens are case sensitive. Tokens are cached for up to 30 seconds, i.e. after adding or deleting a token, it can take a few seconds to become visible.
Tokens are required to view, update or delete logs and required to insert new log rows.
Return value
HTTP status code 200 (Ok).
JSON object containing all tokes, see creating a new log for the token types.
The search parameters shows the required querystring parameters for public dashboards.
[
{
"privilege": "admin",
"token": "XEpzD4p6zyJW795WpKsthUXurCsQ"
},
{
"privilege": "insert",
"token": "ncSZX8Qz8Kqzj9Kbk4F6HR22xAF3"
},
{
"privilege": "view",
"token": "1KxAkipMQDsShjzua8xm1ncdNfsY3",
"search": ""
}
}
Header: authorization
Required, use an admin token
Show all tokens belonging to a log.
curl -H "Authorization: XEpzD4p6zyJW795WpKsthUXurCsQ" \
https://txtlog.net/api/token
Create new token
Create a new token, max 100 different tokens per log can be created.
Return value
HTTP status code 201 (Created).
JSON containing a new token.
{
"token": "XEpzD4p6zyJW795WpKsthUXurCsQ"
}
scope
Required, must be one of these: admin, insert or view.
Admin tokens grant unrestricted access to a log. Insert tokens can only be used for inserting rows, view tokens can only be used for viewing logs.
Header: authorization
Required, use an admin token
Create a new admin token.
curl -H "Authorization: XEpzD4p6zyJW795WpKsthUXurCsQ" \
https://txtlog.net/api/token \
-d 'scope=admin'
Create a new view token with a fixed selection (public dashboard), i.e. the search parameter is always at least "user1" and "firefox"
curl -H "Authorization: XEpzD4p6zyJW795WpKsthUXurCsQ" \
https://txtlog.net/api/token?data=user1+firefox \
-d 'scope=view'
Delete token
Tokens can be created and deleted at any time but at least one admin token must remain.
Return value
HTTP status code 200 (Ok).
JSON containing details.
{
"status": "success",
"detail": "Removed token SJA5fKSaXVwDRkWC7ZcB9B41CPGx"
}
Header: authorization
Required, use an admin token
token
Provide the token to delete in POST parameter.
Delete token SJA5fKSaXVwDRkWC7ZcB9B41CPGx
curl -H "Authorization: XEpzD4p6zyJW795WpKsthUXurCsQ" \
https://txtlog.net/api/token \
-X DELETE \
-d 'token=SJA5fKSaXVwDRkWC7ZcB9B41CPGx'
Errors
API calls can fail with any of the errors listed here.
ERROR_FORBIDDEN
403 ‐ authorization is not provided or invalid
ERROR_INVALID_ACTION
400 ‐ client requested an unknown API endpoint
ERROR_INVALID_JSON
400 ‐ the action requires JSON but the input is not valid JSON
ERROR_INVALID_USERNAME
400 ‐ a username was provided but it contains invalid characters
ERROR_METHOD_NOT_ALLOWED
405 ‐ the API support GET, POST, PATCH and DELETE but something else was provided
ERROR_NO_SERVER_AVAILABLE
500 ‐ the backend cannot find a server to process the incoming request, try again later
ERROR_NO_VALID_ROWS
400 ‐ none of the provided row(s) are valid when trying to insert new rows
ERROR_NOT_FOUND
404 ‐ the requested log is not found
ERROR_PROVIDE_SCOPE_ADMIN_INSERT_VIEW
400 ‐ generating new tokens requires a scope, consult the documentation
ERROR_SERVICE_UNAVAILABLE
503 ‐ connection to the backend database failed, try again later
ERROR_TOO_MANY_REQUESTS
429 ‐ too many requests, try again later
ERROR_TOKEN_LIMIT_REACHED
400 ‐ too many tokens generated
ERROR_UNKNOWN
500 ‐ something terrible happened but we don't know what, try again later
ERROR_USERNAME_ALREADY_EXISTS
400 ‐ creating a new log failed because the username is already taken