api_endpoints

API Endpoints for PlantDB client.

This module provides helper functions to construct URL paths for the PlantDB REST API. Each function returns the endpoint string with an optional prefix and performs basic sanitization of identifiers.

Key Features

• Sanitizes and validates scan, fileset, and file names.
• Supports optional URL prefixes for API versioning.
• Generates paths for authentication, health checks, scans, images, and archives.

Usage Examples

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.login()
'/api/v1/auth/login'
>>> api_endpoints.scan('plant1')
'/api/v1/scans/plant1'

Resource mapping

Hereafter we detail the hierarchy of the resources defined in plantdb.server.api.* submodules and the Flask REST API in the plantdb.server.cli.fsdb_rest_api submodule.

/api/v1/
      ├─ health       (GET) → REST API status
      ├─ refresh/     (GET) → Reload the whole database
      │   └─ {scan_id}     (GET) → Reload the scan
      ├─ auth/
      │   ├─ login         (POST) → user login
      │   ├─ logout        (POST) → user logout
      │   ├─ register      (POST) → new user registration
      │   └─ tokens/
      │       ├─ refresh            (GET) → retrieve a specific scan
      │       ├─ validation         (GET) → retrieve a specific scan
      │       └─ create-api-token   (POST) → create-api-token
      ├─ scans/
      │   ├─ (GET)     → list scans
      │   ├─ info      (GET) → list scans
      │   └─ {scan_id}/
      │       ├─ (GET)    → retrieve a specific scan
      │       ├─ (POST)   → create a new scan
      │       ├─ metadata/
      │       │   ├─ (GET)   → get `scan_id` metadata
      │       │   └─ (POST)  → update `scan_id` metadata
      │       └─ filesets   (GET) → list filesets for scan
      ├─ filesets/
      │   └─ {scan_id}/
      │       └─ {fileset_id}/
      │           ├─ (POST)      → create new fileset
      │           ├─ metadata/
      │           │   ├─ (GET)   → get `scan_id/fileset_id` metadata
      │           │   └─ (POST)  → update `scan_id/fileset_id` metadata
      │           └─ files      (GET) → list files
      ├─ files/
      │   └─ {scan_id}/
      │       └─ {fileset_id}/
      │           └─ {file_id}/
      │               ├─ (GET)       → retrieve file
      │               ├─ (POST)      → create new file
      │               └─ metadata/   → (GET, POST)
      │                   ├─ (GET)   → get `scan_id/fileset_id/file_id` metadata
      │                   └─ (POST)  → update `scan_id/fileset_id/file_id` metadata
      └─ assets/
          ├─ files/{file_path}      (GET) → retrieve a specific scan
          ├─ archive/{scan_id}
          │   ├─ (GET)              → retrieve scan archive
          │   └─ (POST)             → create a new scan by uploading a scan archive
          ├─ image/{scan_id}/{fileset_id}/{file_id}
          │   ├─ (GET)              → get `scan_id/fileset_id/file_id` image
          │   └─ (POST)             → create a new `scan_id/fileset_id/file_id` image
          ├─ pointcloud/{scan_id}   (GET) → retrieve scan pointcloud
          ├─ mesh/{scan_id}         (GET) → retrieve scan triangular mesh
          ├─ sequence/{scan_id}     (GET) → retrieve scan sequence
          └─ skeleton/{scan_id}     (GET) → retrieve scan skeleton

api_prefix

api_prefix(endpoint_path)

Wrap an endpoint path generator with an optional URL prefix.

The prefix keyword argument, when given, represents a deployment prefix (e.g. /plantdb for a reverse-proxy at that path). It is composed in front of the API version prefix (API_PREFIX = "/api/v1").

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.login()
'/api/v1/auth/login'
>>> api_endpoints.login(prefix='/plantdb')
'/plantdb/api/v1/auth/login'
>>> api_endpoints.login(prefix=None)
'/api/v1/auth/login'

Source code in plantdb/commons/api_endpoints.py

def api_prefix(endpoint_path):
    """Wrap an endpoint path generator with an optional URL prefix.

    The ``prefix`` keyword argument, when given, represents a **deployment prefix**
    (_e.g._ ``/plantdb`` for a reverse-proxy at that path).  It is composed
    **in front of** the API version prefix (``API_PREFIX = "/api/v1"``).

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.login()
    '/api/v1/auth/login'
    >>> api_endpoints.login(prefix='/plantdb')
    '/plantdb/api/v1/auth/login'
    >>> api_endpoints.login(prefix=None)
    '/api/v1/auth/login'
    """

    def wrapper(*args, **kwargs):
        deploy_prefix = kwargs.pop("prefix", "") or ""
        deploy_prefix = deploy_prefix.strip("/")
        # Assemble parts, filtering out empty components
        parts = [p for p in [deploy_prefix, API_PREFIX.strip("/")] if p]
        composed_prefix = "/" + "/".join(parts) if parts else ""
        raw = endpoint_path(*args, **kwargs)  # e.g. "/auth/login" or "/"
        return composed_prefix + raw

    return wrapper

archive

archive(scan_id, **kwargs)

Return the URL path to the dataset archive endpoint.

Parameters:

Name	Type	Description	Default
scan_id	str	The name of the scan dataset to archive.	required

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the dataset archive endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.archive('scan1')
'/api/v1/assets/archive/scan1'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def archive(scan_id: str, **kwargs) -> str:
    """Return the URL path to the dataset archive endpoint.

    Parameters
    ----------
    scan_id : str
        The name of the scan dataset to archive.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the dataset archive endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.archive('scan1')
    '/api/v1/assets/archive/scan1'
    """
    scan_id = sanitize_name(scan_id)
    return ARCHIVE.format(scan_id=scan_id)

create_api_token

create_api_token(**kwargs)

Return the URL path to the API token creation endpoint.

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the API token creation endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.create_api_token()
'/api/v1/auth/token/create-api-token'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def create_api_token(**kwargs):
    """Return the URL path to the API token creation endpoint.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the API token creation endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.create_api_token()
    '/api/v1/auth/token/create-api-token'
    """
    return CREATE_API_TOKEN

file

file(scan_id, fileset_id, file_id, **kwargs)

Return the URL path to the scan/fileset/file endpoint.

Parameters:

Name	Type	Description	Default
scan_id	str	The name of the scan dataset containing the file.	required
fileset_id	str	The name of the fileset containing the file.	required
file_id	str	The name of the file.	required

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the file endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.file('real_plant', 'images', '00000_rgb')
'/api/v1/files/real_plant/images/00000_rgb'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def file(scan_id: str, fileset_id: str, file_id: str, **kwargs) -> str:
    """Return the URL path to the `scan/fileset/file` endpoint.

    Parameters
    ----------
    scan_id : str
        The name of the scan dataset containing the file.
    fileset_id : str
        The name of the fileset containing the file.
    file_id : str
        The name of the file.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the file endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.file('real_plant', 'images', '00000_rgb')
    '/api/v1/files/real_plant/images/00000_rgb'
    """
    scan_id = sanitize_name(scan_id)
    fileset_id = sanitize_name(fileset_id)
    file_id = sanitize_name(file_id)
    return FILE.format(scan_id=scan_id, fileset_id=fileset_id, file_id=file_id)

file_metadata

file_metadata(scan_id, fileset_id, file_id, key=None, **kwargs)

URL to access the file metadata associated with the given scan and fileset name.

Parameters:

Name	Type	Description	Default
scan_id	str	The name of the scan to access.	required
fileset_id	str	The name of the fileset to access.	required
file_id	str	The name of the file to access.	required
key	str	A specific metadata key to fetch.	None

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to file metadata.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.file_metadata('real_plant', 'images', '00000_rgb')
'/api/v1/files/real_plant/images/00000_rgb/metadata'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def file_metadata(scan_id: str, fileset_id: str, file_id: str, key: str | None = None, **kwargs) -> str:
    """URL to access the file metadata associated with the given scan and fileset name.

    Parameters
    ----------
    scan_id : str
        The name of the scan to access.
    fileset_id : str
        The name of the fileset to access.
    file_id : str
        The name of the file to access.
    key : str
        A specific metadata key to fetch.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to file metadata.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.file_metadata('real_plant', 'images', '00000_rgb')
    '/api/v1/files/real_plant/images/00000_rgb/metadata'
    """
    scan_id = sanitize_name(scan_id)
    fileset_id = sanitize_name(fileset_id)
    file_id = sanitize_name(file_id)

    # Assemble optional query parameters
    query: dict[str, str] = {}
    if key is not None:
        query["key"] = str(key)

    query_str = f"?{parse.urlencode(query)}" if query else ""
    return (
            FILE_MD.format(scan_id=scan_id, fileset_id=fileset_id, file_id=file_id)
            + f"{query_str}"
    )

file_path

file_path(file_path, **kwargs)

Return the URL path to the scan/file_path endpoint.

Parameters:

Name	Type	Description	Default
file_path	str	The path to the file in the database.	required

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the file path endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.file_path('real_plant/images/00000_rgb.jpg')
'/api/v1/assets/files/real_plant/images/00000_rgb.jpg'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def file_path(file_path: str, **kwargs) -> str:
    """Return the URL path to the `scan/file_path` endpoint.

    Parameters
    ----------
    file_path : str
        The path to the file in the database.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the file path endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.file_path('real_plant/images/00000_rgb.jpg')
    '/api/v1/assets/files/real_plant/images/00000_rgb.jpg'
    """
    return FILE_PATH.format(file_path=file_path.lstrip("/"))

fileset

fileset(scan_id, fileset_id, **kwargs)

URL path for a fileset belonging to a scan.

Parameters:

Name	Type	Description	Default
scan_id	str	The name of the scan to access.	required
fileset_id	str	The name of the fileset to access.	required

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to file metadata.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.fileset('real_plant', 'images')
'/api/v1/filesets/real_plant/images'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def fileset(scan_id:str, fileset_id:str, **kwargs) -> str:
    """URL path for a fileset belonging to a scan.

    Parameters
    ----------
    scan_id : str
        The name of the scan to access.
    fileset_id : str
        The name of the fileset to access.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to file metadata.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.fileset('real_plant', 'images')
    '/api/v1/filesets/real_plant/images'
    """
    scan_id = sanitize_name(scan_id)
    fileset_id = sanitize_name(fileset_id)
    return FILESET.format(scan_id=scan_id, fileset_id=fileset_id)

fileset_files_list

fileset_files_list(scan_id, fileset_id, **kwargs)

URL to list the file associated with the given scan and filesets names.

Parameters:

Name	Type	Description	Default
scan_id	str	The name of the scan to access.	required
fileset_id	str	The name of the fileset to access.	required

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the filesets list of files.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.fileset_files_list('real_plant', 'images')
'/api/v1/filesets/real_plant/images/files'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def fileset_files_list(scan_id: str, fileset_id: str, **kwargs) -> str:
    """URL to list the file associated with the given scan and filesets names.

    Parameters
    ----------
    scan_id : str
        The name of the scan to access.
    fileset_id : str
        The name of the fileset to access.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the filesets list of files.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.fileset_files_list('real_plant', 'images')
    '/api/v1/filesets/real_plant/images/files'
    """
    scan_id = sanitize_name(scan_id)
    fileset_id = sanitize_name(fileset_id)
    return FILESET_FILES.format(scan_id=scan_id, fileset_id=fileset_id)

fileset_metadata

fileset_metadata(scan_id, fileset_id, key=None, **kwargs)

URL to access the fileset metadata associated with the given scan and fileset name.

Parameters:

Name	Type	Description	Default
scan_id	str	The name of the scan to access.	required
fileset_id	str	The name of the fileset to access.	required
key	str or Noe	A specific metadata key to fetch.	None

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to fileset metadata.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.fileset_metadata('real_plant', 'images')
'/api/v1/filesets/real_plant/images/metadata'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def fileset_metadata(
        scan_id: str, fileset_id: str, key: str | None = None, **kwargs
) -> str:
    """URL to access the fileset metadata associated with the given scan and fileset name.

    Parameters
    ----------
    scan_id : str
        The name of the scan to access.
    fileset_id : str
        The name of the fileset to access.
    key : str or Noe, optional
        A specific metadata key to fetch.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to fileset metadata.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.fileset_metadata('real_plant', 'images')
    '/api/v1/filesets/real_plant/images/metadata'
    """
    scan_id = sanitize_name(scan_id)
    fileset_id = sanitize_name(fileset_id)

    # Assemble optional query parameters
    query: dict[str, str] = {}
    if key is not None:
        query["key"] = str(key)

    query_str = f"?{parse.urlencode(query)}" if query else ""
    return FILESET_MD.format(scan_id=scan_id, fileset_id=fileset_id) + f"{query_str}"

health

health(**kwargs)

Return the URL path to the health endpoint.

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the health endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.health()
'/api/v1/health'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def health(**kwargs) -> str:
    """Return the URL path to the health endpoint.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the health endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.health()
    '/api/v1/health'
    """
    return HEALTH

home

home(**kwargs)

Return the URL path to the home endpoint.

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the home endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.home()
'/api/v1/'
>>> api_endpoints.home(prefix='/plantdb')
'/plantdb/api/v1/'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def home(**kwargs) -> str:
    """Return the URL path to the home endpoint.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the home endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.home()
    '/api/v1/'
    >>> api_endpoints.home(prefix='/plantdb')
    '/plantdb/api/v1/'
    """
    return HOME

image

image(scan_id, fileset_id, file_id, size=None, as_base64=None, **kwargs)

Return the URL path to the image endpoint.

Parameters:

Name	Type	Description	Default
scan_id	str	The name of the scan dataset containing the image.	required
fileset_id	str	The name of the fileset containing the image.	required
file_id	str	The name of the image.	required
size	str or int	The size parameter of the image request.	None
as_base64	bool	A boolean flag indicating whether to return an image as a base64 string.	None

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the image endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.image('real_plant', 'images', '00000_rgb', 'orig', False)
'/api/v1/assets/image/real_plant/images/00000_rgb?size=orig&as_base64=false'
>>> api_endpoints.image('real_plant', 'images', '00000_rgb', 'thumb', True)
'/api/v1/assets/image/real_plant/images/00000_rgb?size=thumb&as_base64=true'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def image(
        scan_id: str,
        fileset_id: str,
        file_id: str,
        size: int | str | None = None,
        as_base64: bool | None = None,
        **kwargs,
) -> str:
    """Return the URL path to the image endpoint.

    Parameters
    ----------
    scan_id : str
        The name of the scan dataset containing the image.
    fileset_id : str
        The name of the fileset containing the image.
    file_id : str
        The name of the image.
    size : str or int, optional
        The size parameter of the image request.
    as_base64 : bool, optional
        A boolean flag indicating whether to return an image as a base64 string.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the image endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.image('real_plant', 'images', '00000_rgb', 'orig', False)
    '/api/v1/assets/image/real_plant/images/00000_rgb?size=orig&as_base64=false'
    >>> api_endpoints.image('real_plant', 'images', '00000_rgb', 'thumb', True)
    '/api/v1/assets/image/real_plant/images/00000_rgb?size=thumb&as_base64=true'
    """
    scan_id = sanitize_name(scan_id)
    fileset_id = sanitize_name(fileset_id)
    file_id = sanitize_name(file_id)

    # Assemble optional query parameters
    query: dict[str, str] = {}
    if size is not None:
        query["size"] = str(size)
    if as_base64 is not None:
        # Use lower-case JSON-style booleans for consistency
        query["as_base64"] = str(as_base64).lower()

    query_str = f"?{parse.urlencode(query)}" if query else ""
    return (
            IMAGE.format(scan_id=scan_id, fileset_id=fileset_id, file_id=file_id)
            + f"{query_str}"
    )

login

login(**kwargs)

Return the URL path to the login endpoint.

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the login endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.login()
'/api/v1/auth/login'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def login(**kwargs) -> str:
    """Return the URL path to the login endpoint.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the login endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.login()
    '/api/v1/auth/login'
    """
    return LOGIN

logout

logout(**kwargs)

Return the URL path to the logout endpoint.

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the logout endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.logout()
'/api/v1/auth/logout'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def logout(**kwargs) -> str:
    """Return the URL path to the logout endpoint.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the logout endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.logout()
    '/api/v1/auth/logout'
    """
    return LOGOUT

mesh

mesh(scan_id, size=None, coords=None, **kwargs)

Return the URL path to the mesh endpoint.

Parameters:

Name	Type	Description	Default
scan_id	str	The name of the scan dataset containing the mesh.	required
size	str or int	Query parameter controlling downsampling. Accepted values: * 'orig' - serve the original point cloud.	None
coords	bool	Query parameter indicating whether to return the vertices coordinates and triangle IDs as JSON. Defaults to 'false', which streams the PLY file.	None

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the mesh endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.mesh('real_plant')
'/api/v1/assets/mesh/real_plant'
>>> api_endpoints.mesh('real_plant', coords=True)

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def mesh(scan_id: str, size: int | str | None = None, coords: bool | None = None, **kwargs) -> str:
    """Return the URL path to the mesh endpoint.

    Parameters
    ----------
    scan_id : str
        The name of the scan dataset containing the mesh.
    size : str or int, optional
        Query parameter controlling downsampling.
        Accepted values:
            * 'orig' - serve the original point cloud.
    coords : bool, optional
        Query parameter indicating whether to return the vertices coordinates and triangle IDs as JSON.
        Defaults to 'false', which streams the PLY file.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the mesh endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.mesh('real_plant')
    '/api/v1/assets/mesh/real_plant'
    >>> api_endpoints.mesh('real_plant', coords=True)
    """
    VALID_SIZES = {"orig"}
    scan_id = sanitize_name(scan_id)

    # Assemble optional query parameters
    query: dict[str, str] = {}
    if size is not None:
        if isinstance(size, int):
            query["size"] = str(size)
        elif isinstance(size, str) and size in VALID_SIZES:
            query["size"] = size.lower()
        else:
            raise ValueError(
                f"Invalid size '{size}'. Valid options: integer value or {VALID_SIZES}"
            )
    if coords is not None:
        query["coords"] = str(coords)

    query_str = f"?{parse.urlencode(query)}" if query else ""
    return MESH.format(scan_id=scan_id) + f"{query_str}"

pointcloud

pointcloud(scan_id, size=None, coords=None, pcd_type='default', **kwargs)

Return the URL path to the point-cloud endpoint.

Parameters:

Name	Type	Description	Default
scan_id	str	The name of the scan dataset containing the point-cloud.	required
size	str or int or float	Query parameter controlling downsampling. Accepted values: * 'orig' - serve the original point cloud. * 'preview' - serve a precomputed preview (default). * A float value - perform on-the-fly voxel downsampling using the specified voxel size. If an invalid string is supplied, the default 'preview' is used.	None
coords	bool	Query parameter indicating whether to return the point coordinates as JSON. Defaults to 'false', which streams the PLY file. If set, returns the data as a list under the 'coordinates' JSON dictionary entry.	None
pcd_type	str or int	Query parameter indicating whether to return the reconstructed point cloud (default) or the ground truth ('type=gt').	'default'

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the point-cloud endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.pointcloud('real_plant')
'/api/v1/assets/pointcloud/real_plant?type=default'
>>> api_endpoints.pointcloud('real_plant', pcd_type='gt')
'/api/v1/assets/pointcloud/real_plant?type=gt'
>>> api_endpoints.pointcloud('real_plant', coords=True)
'/api/v1/assets/pointcloud/real_plant?type=default&coords=True'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def pointcloud(
        scan_id: str,
        size: int | float | str | None = None,
        coords: bool | None = None,
        pcd_type: str = "default",
        **kwargs,
) -> str:
    """Return the URL path to the point-cloud endpoint.

    Parameters
    ----------
    scan_id : str
        The name of the scan dataset containing the point-cloud.
    size : str or int or float, optional
        Query parameter controlling downsampling.
        Accepted values:
            * 'orig' - serve the original point cloud.
            * 'preview' - serve a precomputed preview (default).
            * A float value - perform on-the-fly voxel downsampling using the specified voxel size.
        If an invalid string is supplied, the default 'preview' is used.
    coords : bool, optional
        Query parameter indicating whether to return the point coordinates as JSON.
        Defaults to 'false', which streams the PLY file.
        If set, returns the data as a list under the 'coordinates' JSON dictionary entry.
    pcd_type : str or int, optional
        Query parameter indicating whether to return the reconstructed point cloud (default) or
        the ground truth ('type=gt').

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the point-cloud endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.pointcloud('real_plant')
    '/api/v1/assets/pointcloud/real_plant?type=default'
    >>> api_endpoints.pointcloud('real_plant', pcd_type='gt')
    '/api/v1/assets/pointcloud/real_plant?type=gt'
    >>> api_endpoints.pointcloud('real_plant', coords=True)
    '/api/v1/assets/pointcloud/real_plant?type=default&coords=True'
    """
    VALID_SIZES = {"orig", "preview"}
    VALID_TYPES = ["default", "gt"]
    seq_type = "" if pcd_type not in VALID_TYPES else pcd_type
    scan_id = sanitize_name(scan_id)

    # Assemble optional query parameters
    query: dict[str, str] = {}
    if size is not None:
        if isinstance(size, (int, float)):
            query["size"] = str(size)
        elif isinstance(size, str) and size in VALID_SIZES:
            query["size"] = size.lower()
        else:
            raise ValueError(
                f"Invalid size '{size}'. Valid options: integer value or {VALID_SIZES}"
            )
    if seq_type is not None:
        query["type"] = str(seq_type)
    if coords is not None:
        query["coords"] = str(coords)

    query_str = f"?{parse.urlencode(query)}" if query else ""
    return POINTCLOUD.format(scan_id=scan_id) + f"{query_str}"

refresh

refresh(scan_id=None, **kwargs)

Return the URL path to the dataset archive endpoint.

Parameters:

Name	Type	Description	Default
scan_id	str or None	The name of the scan dataset to archive.	None

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the refresh endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.refresh()
'/api/v1/refresh'
>>> api_endpoints.refresh('scan1')
'/refresh?scan_id=scan1'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def refresh(scan_id: str | None = None, **kwargs) -> str:
    """Return the URL path to the dataset archive endpoint.

    Parameters
    ----------
    scan_id : str or None, optional
        The name of the scan dataset to archive.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the refresh endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.refresh()
    '/api/v1/refresh'
    >>> api_endpoints.refresh('scan1')
    '/refresh?scan_id=scan1'
    """
    params = ""
    if scan_id:
        scan_id = sanitize_name(scan_id)
        params = f"?scan_id={scan_id}"
    return f"{REFRESH}{params}"

register

register(**kwargs)

Return the URL path to the register endpoint.

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the register endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.register()
'/api/v1/auth/register'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def register(**kwargs) -> str:
    """Return the URL path to the register endpoint.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the register endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.register()
    '/api/v1/auth/register'
    """
    return REGISTER

scan

scan(scan_id, **kwargs)

Return the URL path to the scan endpoint.

Parameters:

Name	Type	Description	Default
scan_id	str	The name of the scan to access.	required

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the scan endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.scan('scan1')
'/api/v1/scans/scan1'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def scan(scan_id: str, **kwargs) -> str:
    """Return the URL path to the scan endpoint.

    Parameters
    ----------
    scan_id : str
        The name of the scan to access.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the scan endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.scan('scan1')
    '/api/v1/scans/scan1'
    """
    scan_id = sanitize_name(scan_id)
    return SCAN.format(scan_id=scan_id)

scan_filesets_list

scan_filesets_list(scan_id, **kwargs)

URL to list the filesets associated with the given scan name.

Parameters:

Name	Type	Description	Default
scan_id	str	The name of the scan to access.	required

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to filesets.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.scan_filesets_list('real_plant')
'/api/v1/scans/real_plant/filesets'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def scan_filesets_list(scan_id: str, **kwargs) -> str:
    """URL to list the filesets associated with the given scan name.

    Parameters
    ----------
    scan_id : str
        The name of the scan to access.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to filesets.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.scan_filesets_list('real_plant')
    '/api/v1/scans/real_plant/filesets'
    """
    scan_id = sanitize_name(scan_id)
    return SCAN_FILESETS.format(scan_id=scan_id)

scan_metadata

scan_metadata(scan_id, key=None, **kwargs)

URL to access the metadata associated with the given scan name.

Parameters:

Name	Type	Description	Default
scan_id	str	The name of the scan to access.	required
key	str or None	A specific metadata key to fetch.	None

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to scan metadata.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.scan_metadata('real_plant')
'/api/v1/scans/real_plant/metadata'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def scan_metadata(scan_id: str, key: str | None = None, **kwargs) -> str:
    """URL to access the metadata associated with the given scan name.

    Parameters
    ----------
    scan_id : str
        The name of the scan to access.
    key : str or None, optional
        A specific metadata key to fetch.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to scan metadata.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.scan_metadata('real_plant')
    '/api/v1/scans/real_plant/metadata'
    """
    scan_id = sanitize_name(scan_id)

    # Assemble optional query parameters
    query: dict[str, str] = {}
    if key is not None:
        query["key"] = str(key)

    query_str = f"?{parse.urlencode(query)}" if query else ""
    return SCAN_MD.format(scan_id=scan_id) + f"{query_str}"

scans

scans(**kwargs)

Return the URL path to the scans' endpoint.

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the scans' endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.scans()
'/api/v1/scans'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def scans(**kwargs) -> str:
    """Return the URL path to the scans' endpoint.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the scans' endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.scans()
    '/api/v1/scans'
    """
    return SCANS

scans_info

scans_info(**kwargs)

Return the URL path to the list of scan dataset information endpoint.

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the list of scan dataset information endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.scans_info()
'/api/v1/scans/info'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def scans_info(**kwargs) -> str:
    """Return the URL path to the list of scan dataset information endpoint.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the list of scan dataset information endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.scans_info()
    '/api/v1/scans/info'
    """
    return SCANS_INFO

sequence

sequence(scan_id, seq_type=None, **kwargs)

Return the URL path to the sequence endpoint.

Parameters:

Name	Type	Description	Default
scan_id	str	The name of the scan dataset containing the angles and internodes sequence.	required
seq_type	str	The type of measure to request, in ['all', 'angles', 'internodes', 'fruit_points', 'manual_angles', 'manual_internodes'].	None

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the angles and internodes sequences endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.sequence('real_plant','all')
'/api/v1/assets/sequence/real_plant?type=all'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def sequence(scan_id: str, seq_type: str | None = None, **kwargs) -> str:
    """Return the URL path to the sequence endpoint.

    Parameters
    ----------
    scan_id : str
        The name of the scan dataset containing the angles and internodes sequence.
    seq_type : str, optional
        The type of measure to request, in ``['all', 'angles', 'internodes', 'fruit_points',
         'manual_angles', 'manual_internodes']``.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the angles and internodes sequences endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.sequence('real_plant','all')
    '/api/v1/assets/sequence/real_plant?type=all'
    """
    valid_types = [
        "all",
        "angles",
        "internodes",
        "fruit_points",
        "manual_angles",
        "manual_internodes",
    ]
    seq_type = "all" if seq_type not in valid_types else seq_type
    scan_id = sanitize_name(scan_id)

    # Assemble optional query parameters
    query: dict[str, str] = {}
    if seq_type is not None:
        query["type"] = str(seq_type)

    query_str = f"?{parse.urlencode(query)}" if query else ""
    return SEQUENCE.format(scan_id=scan_id) + f"{query_str}"

skeleton

skeleton(scan_id, **kwargs)

Return the URL path to the skeleton endpoint.

Parameters:

Name	Type	Description	Default
scan_id	str	The name of the scan dataset containing the skeleton.	required

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the skeleton endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.skeleton('real_plant')
'/api/v1/assets/skeleton/real_plant'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def skeleton(scan_id: str, **kwargs) -> str:
    """Return the URL path to the skeleton endpoint.

    Parameters
    ----------
    scan_id : str
        The name of the scan dataset containing the skeleton.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the skeleton endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.skeleton('real_plant')
    '/api/v1/assets/skeleton/real_plant'
    """
    scan_id = sanitize_name(scan_id)
    return SKELETON.format(scan_id=scan_id)

timelapse

timelapse(timelapse_id, **kwargs)

Return the URL path to the timelapse endpoint.

Parameters:

Name	Type	Description	Default
timelapse_id	str	The identifier of the timelapse to access.	required

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the timelapse endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.timelapse('tl1')
'/api/v1/timelapses/tl1'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def timelapse(timelapse_id: str, **kwargs) -> str:
    """Return the URL path to the timelapse endpoint.

    Parameters
    ----------
    timelapse_id : str
        The identifier of the timelapse to access.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the timelapse endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.timelapse('tl1')
    '/api/v1/timelapses/tl1'
    """
    timelapse_id = sanitize_name(timelapse_id)
    return TIMELAPSE.format(timelapse_id=timelapse_id)

timelapse_scans

timelapse_scans(timelapse_id, sort=None, **kwargs)

Return the URL path to the timelapse member scans endpoint.

Parameters:

Name	Type	Description	Default
timelapse_id	str	The identifier of the timelapse to access.	required
sort	str	Sort parameter, e.g. 'timelapse.scheduled'.	None

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the timelapse member scans endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.timelapse_scans('tl1')
'/api/v1/timelapses/tl1/scans'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def timelapse_scans(timelapse_id: str, sort: str | None = None, **kwargs) -> str:
    """Return the URL path to the timelapse member scans endpoint.

    Parameters
    ----------
    timelapse_id : str
        The identifier of the timelapse to access.
    sort : str, optional
        Sort parameter, e.g. 'timelapse.scheduled'.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the timelapse member scans endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.timelapse_scans('tl1')
    '/api/v1/timelapses/tl1/scans'
    """
    timelapse_id = sanitize_name(timelapse_id)
    raw = TIMELAPSE_SCANS.format(timelapse_id=timelapse_id)
    if sort:
        raw = f"{raw}?{parse.urlencode({'sort': sort})}"
    return raw

timelapses

timelapses(**kwargs)

Return the URL path to the timelapses' endpoint.

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the timelapses' endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.timelapses()
'/api/v1/timelapses'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def timelapses(**kwargs) -> str:
    """Return the URL path to the timelapses' endpoint.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the timelapses' endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.timelapses()
    '/api/v1/timelapses'
    """
    return TIMELAPSES

token_refresh

token_refresh(**kwargs)

Return the URL path to the token refresh endpoint.

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the token refresh endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.token_refresh()
'/api/v1/auth/token/refresh'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def token_refresh(**kwargs) -> str:
    """Return the URL path to the token refresh endpoint.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the token refresh endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.token_refresh()
    '/api/v1/auth/token/refresh'
    """
    return TOKEN_REFRESH

token_validation

token_validation(**kwargs)

Return the URL path to the token validation endpoint.

Other Parameters:

Name	Type	Description
prefix	str	An optional prefix to prepend to the URL path.

Returns:

Type	Description
str	The URL path to the token validation endpoint.

Examples:

>>> from plantdb.commons import api_endpoints
>>> api_endpoints.token_validation()
'/api/v1/auth/token/validation'

Source code in plantdb/commons/api_endpoints.py

@api_prefix
def token_validation(**kwargs) -> str:
    """Return the URL path to the token validation endpoint.

    Other Parameters
    ----------------
    prefix : str
        An optional prefix to prepend to the URL path.

    Returns
    -------
    str
        The URL path to the token validation endpoint.

    Examples
    --------
    >>> from plantdb.commons import api_endpoints
    >>> api_endpoints.token_validation()
    '/api/v1/auth/token/validation'
    """
    return TOKEN_VALIDATION