Quick Start

BuiltAPI Python Client is a library that allows you to interact with the BuiltAPI platform. This quick start guide will help you get started with setting up and using the client.

Installation

To install the BuiltAPI Python Client, you can use pip:

pip install builtapi

Basic Example

Here's a basic example to help you get started with the BuiltAPI Python Client.

Step 1: Import Necessary Modules

First, import the necessary modules from the BuiltAPI library:

from builtapi.token import get_token
from builtapi.api.main import BuiltAPI

Step 2: Get Authentication Token

Get authentication token using your credentials

token = get_token(
  username='your_username',
  password='your_password',
  client_id='your_client_id',
  client_secret='your_client_secret',  
)

All the parameters are required, but can be define in environment variables:

Environment Variable	Description	Default Value
BUILTAPI_CLIENT_ID	The client ID for authentication	None
BUILTAPI_CLIENT_SECRET	The client secret for authentication	None
BUILTAPI_CLIENT_USER	The username for authentication	None
BUILTAPI_CLIENT_PASSWORD	The password for authentication	None
BUILTAPI_AUDIENCE	The audience for the token request	https://gateway.builtapi.dev
BUILTAPI_GATEWAY_URL	The URL for the BuiltAPI gateway	https://gateway.builtapi.dev
BUILTAPI_TOKEN_URL	The URL for obtaining the authentication token	https://builtapi-dev.eu.auth0.com/oauth/token
BUILTAPI_DEFAULT_WORKSPACE_ID	The default workspace ID to use for the client	None

Detailed Descriptions

• BUILTAPI_CLIENT_ID: The client ID provided by BuiltAPI for accessing the API.
• BUILTAPI_CLIENT_SECRET: The client secret associated with your client ID.
• BUILTAPI_CLIENT_USER: Your BuiltAPI username.
• BUILTAPI_CLIENT_PASSWORD: Your BuiltAPI password.
• BUILTAPI_AUDIENCE: The audience parameter used for the token request. This is optional and defaults to https://gateway.builtapi.dev.
• BUILTAPI_GATEWAY_URL: The URL for the BuiltAPI gateway. This is optional and defaults to https://gateway.builtapi.dev.
• BUILTAPI_TOKEN_URL: The URL for obtaining the authentication token. This is optional and defaults to https://builtapi-dev.eu.auth0.com/oauth/token.

Step 3: Initialize BuiltAPI Client

Initialize the BuiltAPI client with your workspace ID and the authentication token:

client = BuiltAPI(
  workspace_id='your_workspace_id',
  token=token,
)

If you set all BUILTAPICLIENT* environment variables, you can initialize the client without token:

client = BuilAPI(workspace_id='your_workspace_id')

If you set BUILTAPI_DEFAULT_WORKSPACE_ID environment variable, you can initialize the client without workspace_id:

client = BuiltAPI()

Step 4: Interact with the API

Now you can interact with the BuiltAPI using the client. Here are a few examples:

# Get current entities for workspace
entities = built_api_client.entities.list()
print(f"\nSuccessfully got entities list: {entities}")

# Create new regular entity
created_entity = built_api_client.entities.create(name='entity-test')

print(f'\nSuccessfully created new entity with ID {created_entity.id} and name {created_entity.name}')

created_entity_by_id = built_api_client.entities.oneById(created_entity.id)
print(f"\nSuccessfully got created entity by ID: {created_entity_by_id}")

# Now delete this entity
deleted_entity = built_api_client.entities.remove(created_entity.id)
print(f'\nSuccessfully deleted recently created entity with ID {deleted_entity.id}')

Conclusion This guide provides a quick overview of how to set up and use the BuiltAPI Python Client. You can now start interacting with the BuiltAPI platform using the Python Client library. For more advanced usage and API references, refer to the Advanced Usage and [API Reference] (./python/api) sections.