REST API

The Thieves REST API allows you to programmatically interact with your trackers and alert methods. All API requests require a valid API token.

Authentication

All API requests require a token parameter, passed in the Authorization header as a Bearer token. This token is obtained after a user logs into their account, enters 'Account Settings' and clicks "Create New Token".

All JSON request and response bodies use snake_case for field names (e.g., tracker_id, http_method).

Create Tracker

Endpoint: POST https://negativestarinnovators.com/api/v1/create_tracker

Creates a new tracker.

Request Body (JSON):

{
    "name": "string",
    "url": "string",
    "running": boolean,
    "check_frequency": integer,
    "condition": "string",
    "alert_methods": [integer],
    "tracker_type": "string",
    "delayed_start": integer,
    "http_method": "string",
    "http_headers": {
        "Header-Name": "Header-Value"
    },
    "http_body": "any"
}
                

• name: (Required) The name of the tracker.
• url: (Required) The URL to be tracked.
• running: (Required) true to start the tracker immediately, false otherwise.
• check_frequency: (Required) How often to check the URL (in minutes). The minimum check frequency value is 10 minutes.
• condition: (Required) The condition to check for (e.g., "when tomorrow's weather is forecasted to be raining").
• alert_methods: (Optional) An array of alert method IDs (integers). If provided, notifications will be sent to these alert methods when the condition is met. Can be an empty array or null if no alert methods are to be associated initially.
• tracker_type: (Optional) The type of tracker. Can be "url" or "http". Defaults to "url" if omitted (for backward compatibility).
• delayed_start: (Optional) Integer representing how many seconds to delay the initial start of the tracker. Defaults to 5 seconds if not provided. Must be at least 5.

Fields for tracker_type: "http":

• http_method: (Required if tracker_type is "http") The HTTP method to use. Supported methods are "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS".
• http_headers: (Optional) An object (dictionary) where keys are header names and values are header values. Example: {"Content-Type": "application/json", "X-API-Key": "yourkey"}.
• http_body: (Optional) The raw request body.
  • If your body is JSON, provide it as a parsed JSON object (e.g., {"key": "value"}) or a JSON formatted string (e.g., "{\"key\": \"value\"}"). The backend will attempt to parse string bodies as JSON.
  • For other content types, provide the raw string.
  • This field is typically used with methods like "POST", "PUT", "PATCH". Can be null or an empty string if no body is needed.

Response (JSON):

{
    "success": boolean,
    "message": "string",
    "tracker_id": integer
}
                

Modify Tracker

Endpoint: POST https://negativestarinnovators.com/api/v1/modify_tracker

Modifies an existing tracker. Only fields provided in the request will be updated. Omitted fields will retain their current values (partial update).

Request Body (JSON):

{
    "id": integer,
    "name": "string",
    "url": "string",
    "running": boolean,
    "check_frequency": integer,
    "condition": "string",
    "alert_methods": [integer],
    "tracker_type": "string",
    "delayed_start": integer,
    "http_method": "string",
    "http_headers": {
        "Header-Name": "Header-Value"
    },
    "http_body": "any"
}
                

• id: (Required) The ID of the tracker to modify.
• name: (Optional) The new name of the tracker.
• url: (Optional) The new URL to track.
• running: (Optional) true to start/resume, false to pause.
• check_frequency: (Optional) New check frequency (in minutes). Must meet minimum server requirements.
• condition: (Optional) The new condition.
• alert_methods: (Optional) A new array of alert method IDs. If provided, this will *replace* the existing alert methods for the tracker. Provide an empty array [] to remove all alert methods. If omitted, current alert methods are preserved.
• tracker_type: (Optional) The type of tracker (e.g., "url", "http"). If changing to "http", ensure http_method is also provided or already set for the tracker. If changing from "http" to "url", any existing config_details (like http_method, http_headers, http_body) will typically remain in the database but won't be used by "url" type trackers.
• delayed_start: (Optional) Integer representing how many seconds to delay the start if `running` is set to `true` (and the tracker was not previously running or is being restarted). Defaults to 5 seconds if not provided. Must be at least 5.

Fields for tracker_type: "http" (or when changing to "http"):

• http_method: (Optional, but required if tracker_type is "http" and not already set on the tracker) The HTTP method.
• http_headers: (Optional) New HTTP headers. This will replace existing headers. Provide an empty string "" to clear headers.
• http_body: (Optional) New HTTP body. See `create_tracker` for format. Provide an empty string "" to clear the body.

If an optional field is omitted, its current value will generally be preserved (partial update).

Response (JSON):

{
    "success": boolean,
    "message": "string",
    "tracker_id": integer
}
                

Delete Trackers

Endpoint: DELETE https://negativestarinnovators.com/api/v1/delete_trackers

Deletes one or more trackers.

Request Body (JSON):

{
    "ids": [integer]
}
                

• ids: (Required) An array of tracker IDs (integers) to delete.

Response (JSON):

{
    "success": boolean,
    "message": "string"
}
                

Get Trackers

Endpoint: POST https://negativestarinnovators.com/api/v1/get_trackers

Gets tracker information. If `ids` is omitted or empty in the request body, all trackers for the user are returned.

Request Body (JSON):

{
    "ids": [integer]
}
                

• ids: (Optional) An array of tracker IDs (integers) to retrieve. If omitted or an empty array, all trackers for the user are returned.

Response (JSON):

{
    "success": boolean,
    "message": "string",
    "trackers": [
        {
            "id": integer,
            "user_id": integer,
            "name": "string",
            "url": "string",
            "last_checked": "string (ISO 8601 timestamp) / null",
            "condition": "string",
            "running": boolean,
            "last_result": boolean / null,
            "celery_task_id": "string / null",
            "last_result_description": "string / null",
            "check_frequency": integer,
            "next_scheduled": "string (ISO 8601 timestamp) / null",
            "run_start_time": "string (ISO 8601 timestamp) / null",
            "tracker_type": "string / null",
            "config_details": {
                "http_method": "string",
                "http_headers": {},
                "http_body": "any"
            } / null,
            "alert_methods": [integer]
        }
        // ... more trackers
    ]
}
                

Note:

• config_details will be populated (as an object) for trackers of type 'http' and will be null otherwise.
• alert_methods is an array of alert method IDs associated with this tracker. It can be an empty array if no alert methods are linked.
• Timestamps are typically in ISO 8601 format (e.g., "YYYY-MM-DDTHH:MM:SS.ffffff" or "YYYY-MM-DD HH:MM:SS.ffffff"). Fields can be null if no value is set.

Create Alert Method

Endpoint: POST https://negativestarinnovators.com/api/v1/create_alert_method

Creates a new alert method.

Request Body (JSON):

{
    "name": "string",
    "method": "string",
    "contact_info": "string"
}
               

• name: (Required) A descriptive name for the alert method (e.g., "My Discord Webhook").
• method: (Required) The type of alert method. Must be one of "Email", "Telegram", "Discord Webhook", "Webhook".
• contact_info: (Required) Alert method-specific details. See below.

Contact Info Formats:

• Email: The email address where you want your notifications sent to. The email address needs to be verified.
• Telegram: Leave blank. A token will be generated, which you must send to the @negative_star_innovators_bot by sending '/auth token'.
• Discord Webhook: The Discord webhook URL of the channel where you want notifications to be sent.
• Webhook: Your generic webhook URL. The condition check result will be POSTed here.

Response (JSON):

{
    "success": boolean,
    "message": "string",
    "new_alert_method_id": integer,
    "telegram_token": "string / null"
}
               

telegram_token is only present and non-null if method is "Telegram".

Modify Alert Method

Endpoint: POST https://negativestarinnovators.com/api/v1/modify_alert_method

Modifies an existing alert method's name.

Request Body (JSON):

{
    "id": integer,
    "name": "string"
}
                

• id: (Required) The ID of the alert method you want to modify.
• name: (Required) The new name for the alert method.

Response (JSON):

{
    "success": boolean,
    "message": "string",
    "user_alert_method_id": integer
}
                

Get Alert Methods

Endpoint: POST https://negativestarinnovators.com/api/v1/get_alert_methods

Gets alert method information. If `ids` is omitted or empty in the request body, all alert methods for the user are returned.

Request Body (JSON):

{
    "ids": [integer]
}
                

• ids: (Optional) An array of alert method IDs (integers) to retrieve. If omitted or an empty array, all alert methods for the user are returned.

Response (JSON):

{
    "success": boolean,
    "message": "string",
    "alert_methods": [
        {
            "id": integer,
            "user_id": integer,
            "name": "string",
            "method": "string",
            "contact_info": "string",
            "verified": boolean,
            "status": "string"
        }
        // ... more alert methods
    ]
}
                

Delete Alert Methods

Endpoint: DELETE https://negativestarinnovators.com/api/v1/delete_alert_methods

Deletes one or more alert methods.

Request Body (JSON):

{
    "ids": [integer]
}
                

• ids: (Required) An array of alert method IDs (integers) to delete.

Response (JSON):

{
    "success": boolean,
    "message": "string"
}
                

Get Allowed Checks Remaining

Endpoint: GET https://negativestarinnovators.com/api/v1/get_allowed_checks_remaining

Retrieves the number of allowed checks remaining for the authenticated user. This can be 0 or a positive integer.

Request: No request body.

Response (JSON):

{
    "success": boolean,
    "message": "string",
    "allowed_checks_remaining": integer
}