API integration

Official tracker libraries

Use one of these:

LanguageInstall
PHPcomposer require tirreno/tirreno-tracker
Pythonpip install tirreno_tracker
Node.jsnpm install @tirreno/tirreno-tracker

Repos: PHP, Python, Node.js

API reference

Endpoint

POST /sensor/
Content-Type: application/x-www-form-urlencoded
Api-Key: YOUR_API_KEY

Note: The API uses form-urlencoded format, not JSON.

Required parameters

ParameterDescription
userNameUnique user ID (max 100 chars)
ipAddressIPv4/IPv6 address (invalid IPs default to 0.0.0.0)
urlURL path (max 2047 chars)
eventTimeTimestamp Y-m-d H:i:s.v (defaults to current UTC if invalid)

Optional parameters

ParameterTypeDescription
emailAddressstringEmail address (max 255 chars). Validated and converted to lowercase
userAgentstringBrowser UA (max 511 chars)
firstNamestringUser's first name (max 100 chars)
lastNamestringUser's last name (max 100 chars)
fullNamestringUser's whole name (max 100 chars)
pageTitlestringTitle of visited page (max 255 chars)
phoneNumberstringUser's phone number (max 19 chars)
httpRefererstringReferer HTTP header value (max 2047 chars)
httpMethodstringHTTP method: GET, POST, HEAD, PUT, DELETE, PATCH, TRACE, CONNECT, OPTIONS, LINK, UNLINK
httpCodestringHTTP response status code (must be numeric, defaults to 0)
browserLanguagestringDetected browser language (max 255 chars)
eventTypestringOne of the event types listed below. Defaults to page_view, or page_error if httpCode >= 400
userCreatedstringUser creation timestamp (Y-m-d H:i:s or Y-m-d H:i:s.v)
payloadarrayEvent details for page_search events
fieldHistoryarrayField edit history for field_edit events

Note: Maximum length for all other parameters is 100 characters unless specified above. Parameters exceeding max length are truncated.

Event types

Default: page_view (or page_error if httpCode >= 400)

TypeDescription
page_viewPage visit (default)
page_editPage modification
page_deletePage deletion
page_searchSearch query
page_errorError page
account_loginUser authentication
account_logoutSession end
account_login_failFailed login attempt
account_registrationNew account creation
account_email_changeEmail address change
account_password_changePassword change
account_editAccount profile modification
field_editData modification

Payload parameter

For page_search events:

{
    "eventType": "page_search",
    "payload": {
        "field_id": 179280,
        "value": "search query",
        "field_name": "Country"
    }
}
FieldRequiredDescription
field_idYesUnique identifier for the search field
valueYesThe search query string
field_nameNoHuman-readable field name

Field history parameter

Required for field_edit events. Must be an array of field change objects:

{
    "eventType": "field_edit",
    "fieldHistory": [
        {
            "field_id": 179283,
            "new_value": "Paris",
            "field_name": "User city",
            "old_value": "London",
            "parent_id": "",
            "parent_name": ""
        }
    ]
}
FieldRequiredDescription
field_idYesUnique identifier for the field
new_valueYesThe new field value
field_nameNoHuman-readable field name
old_valueNoThe previous field value
parent_idNoParent record ID (for nested data)
parent_nameNoParent record name

Note: Missing required fields default to "unknown". All values are converted to strings.

Blacklist API

Check if a user or IP is blacklisted:

Request:

POST /api/v1/blacklist/search
Content-Type: application/json
Api-Key: YOUR_API_KEY

{
    "value": "username_or_ip"
}

Response:

{
    "value": "username_or_ip",
    "blacklisted": false
}

Error responses

HTTP status codes returned by the API:

HTTP CodeCause
200Success (no response body)
400Required field missing or invalid format
401Api-Key header missing or API key not found
429Rate limit exceeded
500Internal server error
503Database unavailable

Validation error response (400):

Validation error: "Required field is missing or empty" for key "ipAddress"

Note: Successful requests (200) return no response body.

Logbook error types

The Logbook page in tirreno dashboard tracks all API requests with these status codes:

StatusDescription
SuccessEvent recorded successfully
Validation warningEvent recorded with field corrections (e.g., truncated values)
Critical validation errorEvent rejected due to missing required fields
Critical errorServer error, event not recorded
Rate limit exceededRequest rejected due to rate limiting
________________________________________________________________________________