Api

class Api[source]

Bases: object

An API connection to the server with which you can communicate with your teams, workspaces and projects. Api object is immutable.

Parameters
server_address : str

Address of the server.

token : str

Unique secret token associated with your agent.

retry_count : int, optional

The number of attempts to connect to the server.

retry_sleep_sec : int, optional

The number of seconds to delay between attempts to connect to the server.

external_logger : logger, optional

Logger class object.

ignore_task_id : bool, optional

Raises

ValueError, if token is None or it length != 128

Usage example
import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))
api = sly.Api.from_env()

# Pass values into the API constructor (optional, not recommended)
# api = sly.Api(server_address="https://app.supervise.ly", token="4r47N...xaTatb")

Methods

add_additional_field

Add given key and value to additional_fields dictionary.

add_header

Add given key and value to headers dictionary.

from_credentials

Create Api object using credentials and optionally save them to ".env" file with overriding environment variables.

from_env

Initialize API use environment variables.

get

Performs GET request to server with given parameters.

normalize_server_address

rtype

str

parse_error

Processes error from response.

pop_header

rtype

str

post

Performs POST request to server with given parameters.

Attributes

api_server_address

Get API server address.

add_additional_field(key, value)[source]

Add given key and value to additional_fields dictionary.

Parameters
key : str

New key.

value : str

New value.

Returns

None

Return type

NoneType

add_header(key, value)[source]

Add given key and value to headers dictionary.

Parameters
key : str

New key.

value : str

New value.

Raises

RuntimeError, if key is already set

Returns

None

Return type

NoneType

classmethod from_credentials(server_address, login, password, override=False, env_file='/home/docs/supervisely.env')[source]

Create Api object using credentials and optionally save them to “.env” file with overriding environment variables. If “.env” file already exists, backup will be created automatically. All backups will be stored in the same directory with postfix “_YYYYMMDDHHMMSS”. You can have not more than 5 last backups. This method can be used also to update “.env” file.

Parameters
server_address : str

Supervisely server url.

login : str

User login.

password : str

User password.

override : bool, optional

If False, return Api object. If True, additionally create “.env” file or overwrite existing (backup file will be created automatically), and override environment variables.

env_file : str, optional

Path to your .env file.

Return type

Api

Returns

Api object

Usage example
import supervisely as sly

server_address = 'https://app.supervisely.com'
login = 'user'
password = 'pass'

api = sly.Api.from_credentials(server_address, login, password)
classmethod from_env(retry_count=10, ignore_task_id=False, env_file='/home/docs/supervisely.env')[source]

Initialize API use environment variables.

Parameters
retry_count : int

The number of attempts to connect to the server.

ignore_task_id : bool

path : str

Path to your .env file.

Returns

Api object

Return type

Api

Usage example
import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'

api = sly.Api.from_env()

# alternatively you can store SERVER_ADDRESS and API_TOKEN
# in "~/supervisely.env" .env file
# Learn more here: https://developer.supervise.ly/app-development/basics/add-private-app#create-.env-file-supervisely.env-with-the-following-content-learn-more-here

api = sly.Api.from_env()
get(method, params, retries=None, stream=False, use_public_api=True)[source]

Performs GET request to server with given parameters.

Parameters
method : bool, optional

params : Dict

Dictionary to send in the body of the Request.

retries : Optional[int]

The number of attempts to connect to the server.

stream : Optional[bool]

Define, if you’d like to get the raw socket response from the server.

use_public_api : Optional[bool]

Returns

Response object

Return type

Response

static parse_error(response, default_error='Error', default_message='please, contact administrator')[source]

Processes error from response.

Parameters
response : Response

Request object.

default_error : Optional[str]

Error description.

default_message : Optional[str]

Message to user.

Returns

Number of error and message about curren connection mistake

Return type

int, str

post(method, data, retries=None, stream=False, raise_error=False)[source]

Performs POST request to server with given parameters.

Parameters
method : str

Method name.

data : dict

Dictionary to send in the body of the Request.

retries : int, optional

The number of attempts to connect to the server.

stream : bool, optional

Define, if you’d like to get the raw socket response from the server.

raise_error : bool, optional

Define, if you’d like to raise error if connection is failed. Retries will be ignored.

Returns

Response object

Return type

Response

property api_server_address

Get API server address.

Returns

API server address.

Return type

str

Usage example
import supervisely as sly

api = sly.Api(server_address='https://app.supervisely.com', token='4r47N...xaTatb')
print(api.api_server_address)
# Output:
# 'https://app.supervisely.com/public/api'