-
Notifications
You must be signed in to change notification settings - Fork 1
API
BELY-API is available on PyPI.
pip install bely-apiTo use the API, an API factory can be initialized to manage authentication and all of the routes.
from BelyApiFactory import BelyApiFactory
bely_api = BelyApiFactory(bely_url='https://bely_url/bely')Some API calls require authentication. Use the factory to manage login/logout.
# Login for secured API calls.
bely_api.authenticate_user(username, password)
# To end authenticated session.
bely_api.logout_user()The API client library is created using the OpenAPI specification. This means that it is easy to generate client libraries in various programming languages. All the examples in this documentation use the python client library. The BelyApiFactory is an additional component to simplify creation and management of the generated python client API library.
Note: The OpenAPI spec (
openapi.yaml) is available from the BELY server at the/api/openapi.yamlpath.
This route provides all the functionality to fetch, create, and update log documents, entries, etc.
logbook_api = bely_api.get_logbook_api()Returns a list of available logbooks.
Parameters: None.
Returns: list of logbook type objects.
Example:
logbooks = logbook_api.get_logbook_types()
for logbook in logbooks:
print("%s %d" % (logbook.name, logbook.id))Returns a list of available systems.
Parameters: None.
Returns: list of system objects.
Example:
systems = logbook_api.get_logbook_systems()
for system in systems:
print("%s %d" % (system.name, system.id))Returns a list of available template log documents.
Parameters: None.
Returns: list of template objects.
Example:
templates = logbook_api.get_logbook_templates()
for template in templates:
print("%s %d" % (template.name, template.id))Returns a list of last modified log documents for a specific logbook type.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
logbook_type_id |
int | Yes | ID of the logbook type. |
limit |
int | Yes | Limit count of resulting log documents. |
Returns: list of log document objects.
Example:
logbook_type_id = logbooks[2].id
limit = 100
log_docs = logbook_api.get_log_documents(logbook_type_id, limit)
for log_doc in log_docs:
print(log_doc.name)Returns a list of sections for a particular log document.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
log_document_id |
int | Yes | ID of the log document with sections. |
Returns: list of section objects.
Example:
sections = logbook_api.get_logbook_sections(log_document_id)
for section in sections:
print(section.name)Returns a list of log entries for a log document or section.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
log_document_id |
int | Yes | ID of the log document or section with log entries. |
load_replies |
bool | No | Load replies for each log entry. |
load_reactions |
bool | No | Load reactions for each log entry. |
Returns: list of log entry objects.
Example:
log_entries = logbook_api.get_log_entries(log_document_id)
# Or
log_entries = logbook_api.get_log_entries(sections[0].id)
for log_entry in log_entries:
print(log_entry.log_entry)Returns a log entry object used to create a new log entry with text template if applicable for log document.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
log_document_id |
int | Yes | ID of the log document for the new log entry. |
Returns: a log entry object with template text.
Example:
entry = logbook_api.get_log_entry_template(log_document_id)
print(entry.log_entry)Used to add or update a log entry.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
log_entry |
LogEntry | Yes | Log entry object with required attributes. |
Returns: created or updated log entry object.
Example:
from belyApi import LogEntry
markdown_text = '# Some Markdown\nTEST'
log_entry = LogEntry(item_id=log_document_id, log_entry=markdown_text)
# Or use the template for new entry if applicable.
log_entry = logbook_api.get_log_entry_template(log_document_id)
log_entry.log_entry += markdown_text
# Create log entry
log_entry = logbook_api.add_update_log_entry(log_entry)
# Update log entry
log_entry.log_entry += 'Another Change'
log_entry = logbook_api.add_update_log_entry(log_entry)Used to create a new log document.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
log_document_options |
LogDocumentOptions | Yes | Options object with required attributes (see below). |
LogDocumentOptions fields:
| Name | Type | Required | Description |
|---|---|---|---|
name |
str | Yes | Name of the new log document. |
system_id_list |
list[int] | Yes | List of system IDs. |
logbook_type_id |
int | Yes | Logbook type ID. |
template_id |
int | No | Template ID for the new document. |
skip_default_logbook_type_template |
bool | No | Skip applying the default template for the logbook type. |
Returns: newly created log document object.
Example:
from belyApi import LogDocumentOptions
new_doc_options = LogDocumentOptions(
name='API test doc',
system_id_list=[systems[0].id, systems[1].id],
logbook_type_id=logbooks[0].id,
template_id=templates[0].id
)
new_document = logbook_api.create_logbook_document(log_document_options=new_doc_options)
print(new_document.id)Used to add a new section to a log document.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
log_document_id |
int | Yes | ID of the log document to add the new section to. |
section_name |
str | Yes | Name of the new section. |
Returns: newly created section object.
Example:
section = logbook_api.create_log_document_section(
log_document_id=new_document.id,
section_name="API Test Section"
)
print(section.id)
# Now the section id can be used to add log entries to.Used to upload a file attachment to a log entry.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
log_document_id |
int | Yes | ID of the log document. |
log_id |
int | Yes | ID of the log entry to attach the file to. |
body |
str | Yes | Path to the file to upload. |
append_reference |
bool | No | If True, appends a reference to the attachment in the log entry body. |
file_name |
str | Yes | Name to use for the uploaded file. |
Returns: LogEntryAttachment object with the following attributes:
| Name | Type | Description |
|---|---|---|
markdown_reference |
str | Markdown string to embed the attachment in a log entry. |
download_path |
str | API path to download the attachment. |
original_filename |
str | Original name of the uploaded file. |
stored_filename |
str | Name of the file as stored on the server. |
Example (auto-append):
uploadReference = logbook_api.upload_attachment(log_document_id=10257, log_id=45722, body='./data/AnlLogo.png',
append_reference=True,
file_name='test.jpg')When append_reference=True, the markdown reference is automatically appended to the log entry body.
Example (manual reference):
uploadReference = logbook_api.upload_attachment(log_document_id=10257, log_id=45722, body='./data/AnlLogo.png',
append_reference=False,
file_name='test.jpg')
# Manually add the reference to a log entry
log_entry = logbook_api.get_log_entry_template(log_document_id)
log_entry.log_entry += uploadReference.markdown_reference
log_entry = logbook_api.add_update_log_entry(log_entry)Used to fetch all attachments for a log entry.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
log_document_id |
int | Yes | ID of the log document. |
log_id |
int | Yes | ID of the log entry. |
Returns: list of LogEntryAttachment objects.
Example:
attachments = logbook_api.get_log_entry_attachments(log_document_id=10257, log_id=45722)
for attachment in attachments:
print("%s -> %s" % (attachment.original_filename, attachment.download_path))This route provides functionality to search log documents and log entries.
search_api = bely_api.get_search_api()Search log documents and log entries by text with optional filters.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
search_text |
str | Yes | Search text with wildcard support (? single char, * multiple). |
case_insensitive |
bool | No | Use case insensitive matching. |
logbook_type_id |
list[int] | No | List of logbook type IDs to filter by. |
system_id |
list[int] | No | List of system IDs to filter by. |
user_id |
list[int] | No | List of user IDs to filter by. |
start_modified_date |
datetime | No | Start of last modified date range. |
end_modified_date |
datetime | No | End of last modified date range. |
start_created_date |
datetime | No | Start of creation date range. |
end_created_date |
datetime | No | End of creation date range. |
Returns: a LogbookSearchResults object containing:
-
document_results: list of matching log documents -
log_entry_results: list of matching log entries
Example:
from datetime import datetime
results = search_api.search_logbook(
search_text="Test*",
logbook_type_id=[logbooks[0].id],
system_id=[systems[0].id],
start_created_date=datetime(2025, 12, 1),
end_created_date=datetime(2025, 12, 31),
)
for r in results.document_results or []:
print(f"[{r.object_id}] {r.object_name} | type: {r.logbook_type} | system: {r.system}")
for r in results.log_entry_results or []:
print(f"[{r.object_id}] {r.object_name} | entry: {r.log_entry_id} | type: {r.logbook_type}")This route provides functionality to fetch user and group information. Useful for resolving user IDs for search filters.
users_api = bely_api.get_users_api()Returns a user by username.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
username |
str | Yes | Username of the user. |
Returns: user object.
Example:
user = users_api.get_user_by_username("username")
print("%s %d" % (user.username, user.id))Returns a list of all users.
Parameters: None.
Returns: list of user objects.
Note: The method is named
get_all1()due to auto-generation from the OpenAPI spec. This is a known naming artifact.
Example:
all_users = users_api.get_all1()
for user in all_users:
print("%s %d" % (user.username, user.id))Returns a user group by name.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
group_name |
str | Yes | Name of the group. |
Returns: group object.
Example:
group = users_api.get_group_by_name("admin")
print("%s %d" % (group.name, group.id))Returns a list of all user groups.
Parameters: None.
Returns: list of group objects.
Example:
all_groups = users_api.get_all_groups()
for group in all_groups:
print("%s %d" % (group.name, group.id))In the example below the user creates a new log document in the controls logbook using the controls issue template, updates it, uploads attachments, and performs a search.
from BelyApiFactory import BelyApiFactory
from belyApi import LogDocumentOptions, LogEntry
def find_desired_entity(name, entities, name_attribute='name'):
for entity in entities:
if getattr(entity, name_attribute) == name:
return entity
return None
DESIRED_LOGBOOK_NAME = 'Controls'
DESIRED_TEMPLATE_NAME = "Controls issue"
DESIRED_SYSTEM_NAME = "Software"
bely_api = BelyApiFactory(bely_url='https://bely_url/bely')
bely_api.authenticate_user(username, password)
logbook_api = bely_api.get_logbook_api()
search_api = bely_api.get_search_api()
# Get desired attributes for new log document.
logbooks = logbook_api.get_logbook_types()
systems = logbook_api.get_logbook_systems()
templates = logbook_api.get_logbook_templates()
logbook = find_desired_entity(DESIRED_LOGBOOK_NAME, logbooks, name_attribute='display_name')
system = find_desired_entity(DESIRED_SYSTEM_NAME, systems)
template = find_desired_entity(DESIRED_TEMPLATE_NAME, templates)
# Create new log document
new_document_options = LogDocumentOptions(
name='Example Log Document',
system_id_list=[system.id],
logbook_type_id=logbook.id,
template_id=template.id
)
new_log_document = logbook_api.create_logbook_document(new_document_options)
# Fetch default template log entry
log_entries = logbook_api.get_log_entries(new_log_document.id)
default_entry = log_entries[0]
default_entry_text = default_entry.log_entry
default_entry_text = default_entry_text.replace("# Problem Description",
"# Problem Description\nIssue reported from API")
default_entry.log_entry = default_entry_text
# Update the default entry
default_entry = logbook_api.add_update_log_entry(default_entry)
# Add another log entry
new_log_entry = LogEntry(item_id=new_log_document.id,
log_entry='Here is the solution...')
new_log_entry = logbook_api.add_update_log_entry(new_log_entry)
# Upload attachment and auto-append reference to the log entry
logbook_api.upload_attachment(log_document_id=new_log_document.id, log_id=new_log_entry.id,
body='./data/AnlLogo.png', append_reference=True,
file_name='logo.png')
# Fetch all attachments for the log entry
attachments = logbook_api.get_log_entry_attachments(log_document_id=new_log_document.id, log_id=new_log_entry.id)
for attachment in attachments:
print("%s -> %s" % (attachment.original_filename, attachment.download_path))
# Search example
results = search_api.search_logbook(
search_text="Example", # Required: wildcards supported (? single char, * multiple)
# case_insensitive=True, # Use case insensitive matching
logbook_type_id=[logbook.id], # Filter by logbook type ID(s)
system_id=[system.id], # Filter by system ID(s)
# user_id=[user.id], # Filter by user ID(s)
# start_modified_date=datetime(2026, 1, 1), # Start of last modified date range
# end_modified_date=datetime(2026, 3, 3), # End of last modified date range
# start_created_date=datetime(2025, 12, 1), # Start of creation date range
# end_created_date=datetime(2025, 12, 31), # End of creation date range
)
# All done
bely_api.logout_user()