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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.