Flask API Reference¶

All REST endpoints served by the Plant Tracer Flask application are defined in src/app/flask_api.py and mounted at /api/. This document covers authentication, the standard response envelope, and every endpoint.

For the Lambda (frame/video processing) endpoints, see ClientLambdaAPI.md.

Authentication¶

Most endpoints require an api_key parameter. Pass it as a POST body field or a query-string parameter.

Unauthenticated endpoints:

GET|POST /api/ver
GET|POST /api/config-check
GET|POST /api/register
GET|POST /api/resend-link
Valid key -> request proceeds, user identity resolved from the key.
Invalid or missing key on authenticated API routes -> {"error": true, "message": "Invalid api_key"} with HTTP 403.

API keys are issued per-user and stored in the api_keys DynamoDB table. A user may hold multiple keys (e.g. after re-sending a login link). Keys are sent as a cookie after first login.

Response Envelope¶

Most endpoints return JSON with "error": false on success or "error": true plus "message" on failure. Exceptions:

/api/ver returns {"__version__": "...", "sys_version": "..."}.
/api/get-movie-trackpoints returns CSV by default.

{ "error": false, ... }
{ "error": true, "message": "Human-readable reason" }

Endpoints¶

User & Registration¶

`POST /api/register`¶

Register a new user by email address and course key. Sends a login link by email.

Parameters

Name	Required	Description
`email`	Yes	Email address to register
`course_key`	Yes	Course registration passphrase
`name`	No	User’s display name
`planttracer_endpoint`	No	Base URL for login link in email (defaults to server hostname)

Response

{ "error": false, "message": "Registration key sent to alice@example.com ...", "user_id": "u..." }

Returns error: true if the email is invalid, the course key is invalid, or the course is full. Returns error: true (but still registers the user) if the mailer is not configured.

`POST /api/resend-link`¶

Resend a login link to an already-registered email address.

Parameters

Name	Required	Description
`email`	Yes	Email address of the existing user
`planttracer_endpoint`	No	Base URL for login link in email

Response

{ "error": false, "message": "If you have an account, a link was sent. ..." }

Always returns the same message regardless of whether the email exists (prevents enumeration).

`POST /api/bulk-register`¶

Register multiple users at once. Requires the caller to be a course admin.

Parameters

Name	Required	Description
`api_key`	Yes	Must belong to an admin of `course_id`
`course_id`	Yes	Target course
`email-addresses`	Yes	Newline-delimited list of email addresses. Also accepts comma- or semicolon-delimited values.
`names`	No	Newline-delimited list of display names, positionally matched to `email-addresses`.
`planttracer_endpoint`	No	Base URL for login links in emails

Response

{
  "error": false,
  "message": "Registered 3 email address(es) and sent login links.",
  "user_ids": ["u...", "u...", "u..."]
}

If the mailer is not configured, users are registered but message will note the email failure.

`POST /api/check-api_key`¶

Validate an API key and return the associated user record.

Response

{ "error": false, "userinfo": { "user_id": "u...", "email": "...", ... } }

User Listing¶

`POST /api/list-users`¶

`POST /api/list-users-courses`¶

Both routes are equivalent. Return users and courses visible to the caller.

Behavior by role

Admin: Returns all users enrolled in every course the caller admins, sorted by primary_course_id. Also returns all those courses in the courses list.
Non-admin: Returns only the caller’s own user record and their enrolled courses.

Response

{
  "error": false,
  "users": [
    {
      "user_id": "u...",
      "user_name": "Alice",
      "email": "alice@example.com",
      "primary_course_id": "PlantTracer-101",
      "courses": ["PlantTracer-101"],
      "admin_for_courses": [],
      "first": 1714000000,
      "last":  1714500000
    }
  ],
  "courses": [
    { "course_id": "PlantTracer-101", "course_name": "Intro Biology", ... }
  ]
}

first and last are Unix epoch seconds of the user’s first and most recent login, respectively (aggregated across all their API keys). Both are null if the user has never logged in.

Movies¶

`POST /api/new-movie`¶

Create a movie record and obtain a presigned S3 POST URL for uploading the video file directly to its final S3 key. After upload, the browser requests the first frame from lambda-resize and links the user to Analyze.

Parameters

Name	Required	Description
`api_key`	Yes	Must not be the demo key
`title`	No	Movie title
`description`	No	Movie description
`movie_data_sha256`	Yes	SHA-256 hex digest of the video file (64 chars)
`research_use`	No	`"1"` = yes, `"0"` = no, omit = not answered
`credit_by_name`	No	`"1"` = yes, `"0"` = no, omit = not answered (only meaningful when `research_use=1`)
`attribution_name`	No	Attribution name (only stored when `credit_by_name=1`)
`fpm`	No	Capture interval in frames/minute (time-lapse). Positive number, fractional allowed; stored on the movie and included as `x-amz-meta-fpm` in the presigned post

Response

{
  "error": false,
  "movie_id": "m...",
  "presigned_post": {
    "url": "https://s3.amazonaws.com/...",
    "fields": { ... }
  }
}

`POST /api/list-movies`¶

List all movies visible to the caller (their own movies and published movies in their course; admins additionally see unpublished movies from other users in their course).

Response

{ "error": false, "movies": [ { "movie_id": "m...", "title": "...", ... } ] }

Each movie dict contains all DynamoDB metadata fields. In addition, if the movie has a traced MP4 stored in S3 (movie_traced_urn starts with s3:), the response injects a short-lived presigned URL. Clients should treat needs_retracing=1 as user-visible only when this URL is present; before the first traced MP4 exists there is no stale traced artifact to warn about.

Field	Description
`movie_traced_url`	Presigned S3 URL for downloading the traced MP4; only present when a traced MP4 exists

`POST /api/get-movie-metadata`¶

Get metadata and optionally per-frame trackpoints for a specific movie.

Parameters

Name	Required	Description
`api_key`	Yes
`movie_id`	Yes
`frame_start`	No	First frame number to return trackpoints for
`frame_count`	No	Number of frames (required if `frame_start` is provided; must be ≥ 1)
`get_all_if_tracking_completed`	No	If `"1"` and tracking is complete, return all frames

Response

{
  "error": false,
  "metadata": { "movie_id": "m...", "title": "...", "status": "...", ... },
  "frames": {
    "0": { "markers": [ { "x": 100.0, "y": 200.0, "label": "Apex", ... } ] }
  }
}

frames is only present when frame_start is provided.

`POST /api/get-movie-trackpoints`¶

Download all trackpoints for a movie as CSV (default) or JSON.

Parameters

Name	Required	Description
`api_key`	Yes
`movie_id`	Yes
`format`	No	`"json"` for JSON; omit for CSV

Response: CSV with columns frame_number, <label> x, <label> y for each marker label, served with Content-Type: text/csv and Content-Disposition: attachment; filename="trackpoints.csv" so the browser downloads it rather than displaying it inline. With format=json: { "error": "False", "trackpoint_dicts": [...] }.

`POST /api/put-frame-trackpoints`¶

Write trackpoints for a single frame. Used by the client before requesting re-tracking.

Parameters

Name	Required	Description
`api_key`	Yes	Must not be the demo key
`movie_id`	Yes
`frame_number`	Yes	Zero-based frame index
`trackpoints`	Yes	JSON array of trackpoint objects: `[{"x": 100.0, "y": 200.0, "label": "Apex"}, ...]`

Response

{ "error": false, "message": "trackpoints recorded: 2 " }

Side effect: sets needs_retracing=1 on the movie record. This flag indicates that a previously traced MP4 may now be stale. The client uses it to show the retracing warning when movie_traced_url is also present.

The tracer UI disables marker editing and reset actions while a trace request is active in that browser session, and when loaded movie metadata has status="tracing". This prevents normal same-session marker edits while Lambda is tracing, so Lambda does not finish by clearing needs_retracing for a traced MP4 computed from an earlier marker state.

`POST /api/rename-marker`¶

Rename one marker label across all stored trackpoints for a movie. Other marker properties, such as coordinates, color, undeletable, status, and error metadata, are preserved.

Parameters

Name	Required	Description
`api_key`	Yes	Must not be the demo key
`movie_id`	Yes
`old_label`	Yes	Existing marker label to rename
`new_label`	Yes	New marker label. Must not already exist on the movie.

Response

{ "error": false, "frames_updated": 3, "trackpoints_updated": 3 }

Side effect: when any stored trackpoints are renamed, sets needs_retracing=1 on the movie record. Marker labels are stored in the movie_frames marker-map item at frame_number=-100, so rename updates that marker map and does not rewrite each frame record.

`POST /api/rotate-movie`¶

Set the movie’s rotation. Tracking is cleared; Lambda applies the rotation when re-processing.

Parameters

Name	Required	Description
`api_key`	Yes	Must not be the demo key
`movie_id`	Yes
`rotation`	Yes	Degrees: `0`, `90`, `180`, or `270`

Response

{ "error": false }

`POST /api/delete-movie`¶

Delete or undelete a movie.

Parameters

Name	Required	Description
`api_key`	Yes	Must not be the demo key
`movie_id`	Yes
`delete`	No	`"1"` (default) to delete, `"0"` to undelete

Response

{ "error": false }

`POST /api/set-research-metadata`¶

Set research_use (and optionally credit_by_name) for a movie. Only the movie’s uploader may call this endpoint — course admins are not permitted to change another user’s research metadata. When research_use is set to anything other than "1", credit_by_name is automatically cleared server-side; attribution_name is left intact.

Parameters

Name	Required	Description
`api_key`	Yes	Must belong to the movie’s uploader
`movie_id`	Yes	Movie to update
`research_use`	No	`"1"` = yes, `"0"` = no, omit = not answered
`credit_by_name`	No	`"1"` = yes, `"0"` = no; only applied when `research_use=1`

Response

{ "error": false }

`POST /api/set-movie-trim`¶

Set one inclusive trim bound for a movie. Exactly one of trim_start_frame or trim_end_frame must be provided per call.

Parameters

Name	Required	Description
`api_key`	Yes	Must not be the demo key
`movie_id`	Yes
`trim_start_frame`	Cond.	Zero-based first frame to include in trim (provide this or `trim_end_frame`, not both)
`trim_end_frame`	Cond.	Zero-based last frame to include in trim (inclusive; provide this or `trim_start_frame`, not both)

Response

{ "error": false, "metadata": { "movie_id": "m...", "trim_start_frame": 0, "trim_end_frame": 42, ... } }

Returns HTTP 400 with error: true if both or neither trim frame parameter is provided, or if the resulting trim bounds are invalid (e.g. trim_start_frame > trim_end_frame).

`POST /api/set-movie-fpm`¶

Set the capture interval (frames/minute) for a movie. Owner or course admin only. Editing this value only rescales the Analyze time axis and Rate statistics; it does not require retracing. See docs/Development/AnalysisResults.rst.

Parameters

Name	Required	Description
`api_key`	Yes	Must not be the demo key
`movie_id`	Yes
`fpm`	Yes	Capture interval in frames/minute. Positive number, fractional allowed (e.g. `0.5`)

Response

{ "error": false, "metadata": { "movie_id": "m...", "fpm": "30", ... } }

Returns HTTP 400 with error: true if fpm is missing, non-numeric, not positive, or above the allowed maximum.

`POST /api/set-metadata`¶

Set a single metadata property on a movie or user record.

Parameters

Name	Required	Description
`api_key`	Yes
`set_movie_id`	Cond.	Movie to update (provide this or `set_user_id`)
`set_user_id`	Cond.	User to update (provide this or `set_movie_id`)
`property`	Yes	Property name to set
`value`	Yes	New value

Logging¶

`POST /api/get-logs`¶

Return audit log entries. At least one index filter is required by the database layer (log_user_id, course_id, or ipaddr). If the request provides none, the API defaults to the caller’s own log_user_id.

Parameters (all optional filters)

start_time, end_time, course_id, course_key, movie_id, log_user_id, ipaddr, count, offset

Response

{ "error": false, "logs": [ { "log_id": "...", "time_t": 1714000000, ... } ] }

`POST /api/get-log`¶

Legacy route that calls odb.get_logs(user_id=get_user_id()) with no request filters. Because the database function requires an index filter, prefer /api/get-logs.

Infrastructure¶

`GET|POST /api/ver`¶

Return the application version. No authentication required.

Response

{ "__version__": "0.9.7.6.2", "sys_version": "3.12.x ..." }

`GET|POST /api/config-check`¶

Check DynamoDB connectivity, S3 CORS configuration, and S3 bucket region. No authentication required.

Response

{
  "dynamodb_ok": true,  "dynamodb_message": "...",
  "cors_ok": true,      "cors_message": "...",
  "bucket_region_ok": true, "bucket_region_message": "..."
}

Flask API Reference¶

Authentication¶

Response Envelope¶

Endpoints¶

User & Registration¶

`POST /api/register`¶

`POST /api/resend-link`¶

`POST /api/bulk-register`¶

`POST /api/check-api_key`¶

User Listing¶

`POST /api/list-users`¶

`POST /api/list-users-courses`¶

Movies¶

`POST /api/new-movie`¶

`POST /api/list-movies`¶

`POST /api/get-movie-metadata`¶

`POST /api/get-movie-trackpoints`¶

`POST /api/put-frame-trackpoints`¶

`POST /api/rename-marker`¶

`POST /api/rotate-movie`¶

`POST /api/delete-movie`¶

`POST /api/set-research-metadata`¶

`POST /api/set-movie-trim`¶

`POST /api/set-movie-fpm`¶

`POST /api/set-metadata`¶

Logging¶

`POST /api/get-logs`¶

`POST /api/get-log`¶

Infrastructure¶

`GET|POST /api/ver`¶

`GET|POST /api/config-check`¶

Plant Tracer Web Application

Navigation

Related Topics

Flask API Reference¶

Authentication¶

Response Envelope¶

Endpoints¶

User & Registration¶

POST /api/register¶

POST /api/resend-link¶

POST /api/bulk-register¶

POST /api/check-api_key¶

User Listing¶

POST /api/list-users¶

POST /api/list-users-courses¶

Movies¶

POST /api/new-movie¶

POST /api/list-movies¶

POST /api/get-movie-metadata¶

POST /api/get-movie-trackpoints¶

POST /api/put-frame-trackpoints¶

POST /api/rename-marker¶

POST /api/rotate-movie¶

POST /api/delete-movie¶

POST /api/set-research-metadata¶

POST /api/set-movie-trim¶

POST /api/set-movie-fpm¶

POST /api/set-metadata¶

Logging¶

POST /api/get-logs¶

POST /api/get-log¶

Infrastructure¶

GET|POST /api/ver¶

GET|POST /api/config-check¶

`POST /api/register`¶

`POST /api/resend-link`¶

`POST /api/bulk-register`¶

`POST /api/check-api_key`¶

`POST /api/list-users`¶

`POST /api/list-users-courses`¶

`POST /api/new-movie`¶

`POST /api/list-movies`¶

`POST /api/get-movie-metadata`¶

`POST /api/get-movie-trackpoints`¶

`POST /api/put-frame-trackpoints`¶

`POST /api/rename-marker`¶

`POST /api/rotate-movie`¶

`POST /api/delete-movie`¶

`POST /api/set-research-metadata`¶

`POST /api/set-movie-trim`¶

`POST /api/set-movie-fpm`¶

`POST /api/set-metadata`¶

`POST /api/get-logs`¶

`POST /api/get-log`¶

`GET|POST /api/ver`¶

`GET|POST /api/config-check`¶