Cloud API Overview

The pydoover Cloud API provides a Python interface for interacting with the Doover platform. It enables programmatic access to agents, channels, messages, applications, and remote tunnel management.

Key Features

Agent Management: Retrieve and manage agents in your Doover organization
Channel Operations: Create, read, and publish to channels for state management
Message Handling: Send and retrieve messages with support for time-windowed queries
Application Lifecycle: Create and update applications programmatically
Tunnel Management: Set up remote access tunnels to devices

Installation

The Cloud API is included with the pydoover package:

pip install pydoover

Quick Start

from pydoover.cloud.api import Client

# Initialize with username/password
client = Client(username="your_username", password="your_password")

# Or use a pre-existing token
client = Client(token="your_access_token")

# Or use stored configuration profile
client = Client(config_profile="default")

# Get all agents you have access to
agents = client.get_agent_list()
for agent in agents:
    print(f"Agent: {agent.name} ({agent.key})")

# Get a specific agent
agent = client.get_agent("agent-uuid-here")

# Create and publish to a channel
channel = client.create_channel("my-channel", agent.key)
channel.publish({"status": "online", "temperature": 25.5})

Module Exports

The pydoover.cloud.api module exports the following classes:

Class	Description
`Client`	Main API client for authentication and operations
`Agent`	Represents an agent in the Doover system
`Channel`	Base channel class for state storage
`Processor`	Processor channel for lambda-like functions
`Task`	Task channel that triggers processors
`Message`	Represents a message in a channel
`ConfigManager`	Manages stored configuration profiles
`ConfigEntry`	Individual configuration entry

Exception Classes

Exception	Description
`DooverException`	Base exception for all Doover API errors
`HTTPException`	Raised for HTTP-related issues
`NotFound`	Raised when a resource is not found
`Forbidden`	Raised when access to a resource is forbidden

Authentication Methods

The Cloud API supports multiple authentication methods:

Username and Password

client = Client(
    username="your_email@example.com",
    password="your_password",
    base_url="https://my.doover.dev"  # Optional, this is the default
)

Token-Based Authentication

from datetime import datetime, timezone

client = Client(
    token="your_access_token",
    token_expires=datetime(2024, 12, 31, tzinfo=timezone.utc)  # Optional
)

Configuration Profile

# Uses the "default" profile from stored configuration
client = Client()

# Or specify a profile
client = Client(config_profile="production")

Two-Factor Authentication

If your account has 2FA enabled, it is recommended to use a long-lived token via doover configure_token rather than username/password authentication.

API Sections

Section	Description
Client Reference	Complete Client class API reference
Agent Management	Working with agents
Channels and Messaging	Channel operations and message handling
Application Management	Creating and updating applications

Common Patterns

Error Handling

from pydoover.cloud.api import Client, NotFound, Forbidden, HTTPException

client = Client()

try:
    agent = client.get_agent("some-agent-id")
except NotFound:
    print("Agent not found or you don't have access")
except Forbidden:
    print("Access denied to this agent")
except HTTPException as e:
    print(f"HTTP error occurred: {e}")

Working with Channels

# Get a channel by ID
channel = client.get_channel("channel-uuid")

# Get a channel by name for a specific agent
channel = client.get_channel_named("my-channel", agent_id="agent-uuid")

# Publish data to a channel
client.publish_to_channel(
    channel_id="channel-uuid",
    data={"key": "value"},
    save_log=True
)

Fetching Messages

# Get recent messages from a channel
messages = client.get_channel_messages("channel-uuid", num_messages=10)

# Get messages in a time window
from datetime import datetime, timedelta

end = datetime.now()
start = end - timedelta(hours=1)
messages = client.get_channel_messages_in_window("channel-uuid", start, end)