Skip to main content

Python >=3.11 PyPI - Version Python tests

Code style: black Nox

trackbear-api


Python library for synchronous HTTP calls to the Trackbear API (https://help.trackbear.app/api)

Deveploment in progress, expect breaking changes frequently until version 0.1.0

Routes pending implementation:

  • Other

Features pending implementation:

  • Rate limit exceptions

Installation

python -m pip install trackbear-api

Environment Variables

The following environment variables allow you to configure the TrackBearClient outside of code. All variables listed below can also be set during the initialization of the TrackBearClient as well.

Variable Description Has Default Default
TRACKBEAR_API_TOKEN Your secret API token False
TRACKBEAR_API_URL The URL of the TrackBear API True https://trackbear.app/api/v1/
TRACKBEAR_API_AGENT The User-Agent header sent with requests True trackbear-api/0.x.x (https://github.com/Preocts/trackbear-api) (app name: [app_name])
TRACKBEAR_API_TIMEOUT_SECONDS Seconds before HTTPS reqeusts timeout True 10

Example Use

The TrackBearClient give you all of the access to the TrackBear API. Various routes of the API, such as Projects, are available through the TrackBearClient from their respective attribute.

Error handling removed for brevity.

from trackbear_api import TrackBearClient
from trackbear_api.enums import Phase

# Assumes TRACKBEAR_API_TOKEN is set in the environment
client = TrackBearClient("my_app")

# Create a new Project
new_project = client.project.save(
    title="My new TrackBear project",
    description="This will be an amazing story!",
    phase=Phase.OUTLINING,  # "outlining" as a string works here too
    starred=True,
    word=1667,
)

print(f"New Project created ({new_project.id}) '{new_project.title}'")

# List all projects
projects = client.project.list()

print(f"| {'Project Id':^12} | {'Title':^30} | {'Word Count':^12} |")
print("-" * 64)
for project in projects:
    print(f"| {project.id:<12} | {project.title:<30} | {project.totals.word:<12} |")

Library API

The library's API is build to match TrackBear's API general structure.

https://help.trackbear.app/api/

Tallies

Provider Method Description
TrackBearClient.tally Contains helper methods for all Tally related routes
Method Description
.list() Get all tallies, or filter by parameters
.get() Get a tally by specific id
.save() Create or update tally
.delete() Delete a tally by its id

Projects

Provider Method Description
TrackBearClient.project Contains helper methods for all Project related routes
Method Description
.list() Get all projects
.get() Get a project by specific id
.save() Create or update project
.delete() Delete a project by its id

Goals

Provider Method Description
TrackBearClient.goal Contains helper methods for all Goal related routes
Method Description
.list() Get all goals
.get() Get a goal by specific id
.save_target() Create or update target goal
.save_habit() Create or update habit goal
.delete() Delete a goal by its id

Tags

Provider Method Description
TrackBearClient.tag Contains helper methods for all Tag related routes
Method Description
.list() Get all tags
.get() Get a tag by specific id
.save() Create or update tag
.delete() Delete a tag by its id

Stats

Provider Method Description
TrackBearClient.stat Contains helper methods for all Stat related routes
Method Description
.list() Get stats. By default returns all stats.

Leaderboards

Provider Method Description
TrackBearClient.leaderboard Contains helper methods for all Leaderboard related routes
Method Description
.list() Get all leaderboards
.list_participants() Get a leaderboard's participants
.get() Get a leaderboard by specific uuid
.get_by_join_code() Get a leaderboard by specific join code
.save() Create or update a leaderboard
.star() Star a Leaderboard
.unstar() Unstar a Leaderboard
.delete() Delete a leaderboard by uuid

Leaderboard Teams

Provider Method Description
TrackBearClient.leaderboard.teams Contains helper methods for all leaderboard Team related routes
Method Description
.list() Get all teams on a leaderboard
.get() Get a specific team from a leaderboard
.save() Create or update a team on a leaderboard
.delete() Delete a team from a leaderboard

Leaderboard Members

Provider Method Description
TrackBearClient.leaderboard.members Contains helper methods for all leaderboard Members related routes
Method Description
.list() Get all members on a leaderboard
.set_owner() Set a member as an owner of a leaderboard
.unset_owner() Remove ownership of a member of a leaderboard
.delete() Delete a member from a leaderboard

Leaderboard Participation

Provider Method Description
TrackBearClient.leaderboard.participation Contains helper methods for all leaderboard participation related routes
Method Description
.get() Get your participation of a leaderboard
.join() Join a leaderboard
.update() Update your participant details of a leaderboard
.leave() Leave a leaderboard

Bare Access

Bare access to the API allows you to escape from the structured return models and call routes directly. These methods return a models.TrackBearResponse object.

Provider Method Description
TrackBearClient.bare Escape hatch allowing manually defined calls to API
Method Description
.get() HTTP GET to the TrackBear API
.post() HTTP POST to the TrackBear API
.patch() HTTP PATCH to the TrackBear API
.delete() HTTP DELETE to the TrackBear API

trackbear_api.models.TrackBearResponse

Attribute Type Description
.success bool True or False if the request was succesful.
.data Any API response if success is True
.error.code str Error code if success is False
.error.message str Error message if success is False
.status_code int The HTTP status code of the response
.remaining_requests int Number of requests remaining before rate limits apply
.rate_reset int Number of seconds before remaining_requests resets

Exceptions

The library defines a handful of useful custom exceptions.

trackbear_api.exceptions.TrackBearAPIException

Parent class of all exceptions defined in the library. Inherits from Exception.

trackbear_api.exceptions.ModelBuildError

Raised when building a dataclass model from the API response fails. This can indicate the expected response has changed from the observed response. The exception contains the model name that failed and the data the model attempted to build with. Both are vital for bug reports.

Attribute Type Description
data_string str The data which caused the model build to fail
model_name str The name of the model that failed

trackbear_api.exceptions.APIResponseError

Raised by all provider methods when the API returns an unsuccessful response.

Attribute Type Description
status_code int HTTP status code returned by the API
code str Error code provided by the API
message str Human readable error message provided by the API

trackbear_api.exceptions.APITimeoutError

Raised when the TrackBear API request, read, or connection times out.

Attribute Type Description
exception Exception Exception raised by internal HTTP library
method str HTTP method
url str Target URL
timeout int Timeout length in seconds

Rate Limiting

Rate limiting is defined by the TrackBear API here: https://help.trackbear.app/api/rate-limits

This library does not presently enforce the rate limits.

Logging

All loggers use the name trackbear-api. No handlers are defined by default in this library.

Metadata

Release files for trackbear-api 0.0.15

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for trackbear-api 0.0.15
File Size Uploaded Provenance Actions
trackbear_api-0.0.15.tar.gz 96.3 kB With provenance Details for trackbear_api-0.0.15.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for trackbear-api 0.0.15
File Interpreter ABI Platform Actions
trackbear_api-0.0.15-py3-none-any.whl Python 3 none any Details for trackbear_api-0.0.15-py3-none-any.whl

Total release size: 123.9 kB

Release files / trackbear_api-0.0.15.tar.gz

Download URL trackbear_api-0.0.15.tar.gz
Size 96.3 kB
Tags Source
SHA-256 checksum
How to use checksums
12fda6c31e4adad832e8e0073906e1e716b667e4c85440842f7e6ee232a794c2
BLAKE2b-256 checksum
How to use checksums
8831220ce07d9daab68f620407104c73e8d8038ec8410144a3db5752ff191646
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.

Transparency log

Release files / trackbear_api-0.0.15-py3-none-any.whl

Download URL trackbear_api-0.0.15-py3-none-any.whl
Size 27.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b3e14a781db653c5b549274eff9b9909953eabb0d6377912bcf7beba9f20172e
BLAKE2b-256 checksum
How to use checksums
1227b3f80edc56302122009c577fd6b52d2e86ee453e1e45286bac55eab1c76c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.

Transparency log

Security for trackbear-api 0.0.15

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for trackbear_api-0.0.15.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 24, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page