Log Endpoints

Endpoints under https://treeid.io/api/v3/log. Auth via ?key= query param. Requires a USER key or higher.

Auth: ?key=your-api-key Image format: Base64 string Filename: <uuid>.jpg or .jpeg Timing in time object

POST /api/v3/log USER

Insert Image

Uploads, segments, and stores a log image. Requires INSERT or ALL permission.

Request Body

{
  "image":     "base64-encoded-image",
  "filename":  "550e8400-e29b-41d4-a716-446655440000.jpg",
  "lat":       59.3293,
  "long":      18.0686,
  "timestamp": "1970-01-01 14:26:30.895357+00",
  "diameter":  24,
  "end":       "small",
  "species":   "pine"
}

Required Fields

image — Base64 string.
filename — <uuid>.jpg or <uuid>.jpeg.
lat
long
timestamp
diameter

Optional Fields

end — "small" or "large".
species

Optional Query Params

include_mask=true — also return the segmented mask as Base64.

Success Response

{
  "status": "Created",
  "mask":   "optional-base64-encoded-mask",
  "time": {
    "image processing":  "12ms",
    "image segmenting":  "320ms",
    "image insert":      "7ms"
  }
}

Error Responses

{ "status": "UUID already exists",                                                "time": {...} }
{ "status": "Invalid request parameters: one or more provided values are malformed.", "time": {...} }
{ "status": "Unable to generate mask from the provided input.",                   "time": {...} }
{ "status": "Not permitted to INSERT",                                            "time": {} }

POST /api/v3/log/match USER

Match Uploaded Image

Segments an image and compares it against stored logs using metadata filters. Requires MATCH or ALL permission.

Request Body

{
  "image":             "base64-encoded-image",
  "from_long":         17.0,
  "from_lat":          58.0,
  "to_long":           19.0,
  "to_lat":            60.0,
  "from_capture_date": "1970-01-01 14:26:30.895357+00",
  "to_capture_date":   "1970-01-02 14:26:30.895357+00",
  "min_diameter":      10,
  "max_diameter":      40,
  "end":               "small",
  "species":           "pine"
}

Required Fields

image — Base64 string.
from_long
from_lat
to_long
to_lat
from_capture_date
to_capture_date
min_diameter
max_diameter

Optional Fields

end
species

Optional Query Params

include_mask=true — return the segmented query mask as Base64.
include_match=true — return the matched stored image as Base64.
include_kp_map=true — return normalised keypoint arrays and the matched image.

Success Response

{
  "matches":       "1234",
  "matched_uuid":  "808149cd-4444-4d69-9b2a-f71b5d60b85e",
  "mask":          "optional-base64-encoded-mask",
  "matched_image": "optional-base64-encoded-image",
  "keypoints":     [[...], [...]],
  "time": {
    "image processing":  "12ms",
    "image segmenting":  "320ms",
    "image matched":     "120ms"
  }
}

Error Responses

{ "status": "Unable to generate mask from the provided input.", "time": {...} }
{ "status": "Not permitted to MATCH",                          "time": {} }

POST /api/v3/log/metadata USER

View Log Metadata

Returns metadata for all logs belonging to the authenticated user (or organisation/sysadmin, scoped accordingly).

Request Body

No fields required beyond the key query parameter.

Success Response

{
  "entries":    2,
  "uuid":       ["...", "..."],
  "user_uuid":  ["...", "..."],
  "lat":        [59.3293, 59.33],
  "long":       [18.0686, 18.07],
  "diameter":   [24, 18],
  "species":    ["pine", null],
  "log_end":    ["small", "large"],
  "created_at": ["2024-01-01T12:00:00+00:00", "..."]
}

Error Responses

500  { "status": "DB error" }

POST /api/v3/log/thumbnail USER

View Thumbnail

Returns a stored thumbnail for a given log file.

Request Body

{
  "filename": "550e8400-e29b-41d4-a716-446655440000.jpg",
  "end":      "small"
}

Required Fields

filename

Optional Fields

end — "small" or "large".

Success Response

{ "thumbnail": "base64-encoded-image" }

Error Responses

400  { "status": "Invalid end provided" }
500  { "status": "Could not fetch user's organization" }

DELETE /api/v3/log/<log_uuid> USER

Delete Single Log by UUID

Removes one specific log entry by UUID. Requires ALL permission.

Path Param

log_uuid = "550e8400-e29b-41d4-a716-446655440000"

Request Body

{
  "end": "small"
}

Required Fields

end

Success Response

{
  "status": "Entry removed successfully.",
  "time": { "Log deletion time": "4ms" }
}

Error Responses

{ "status": "UUID not found",            "time": {...} }
{ "status": "Error while removing entry", "time": {...} }
{ "status": "Not permitted to DELETE",    "time": {} }

DELETE /api/v3/log/ ORGANIZATION

Delete All Logs for a User

Removes all stored log entries for a given user. Requires an ORGANIZATION key.

Request Body

{
  "user_uuid": "550e8400-e29b-41d4-a716-446655440000"
}

Required Fields

user_uuid — the user whose logs should be removed.

Success Response

{
  "status": "Entries removed successfully.",
  "time": { "Log deletion time": "5ms" }
}

Error Responses

401  { "status": "The provided USER-API key is invalid" }
500  { "status": "Not permitted to DELETE", "time": {} }
     { "status": "Error while removing entries", "time": {} }