Botlink Documentation

API Reference

This page documents the public SDK client behaviour and the JSON payloads exchanged with the Botlink server. The SDK provides a small, synchronous Python client that validates your API key, exposes your projects as a lazy registry, and lets you chat with an agent associated with a project.

Base URL

All SDK requests are proxied through the Botlink server at:

https://botlink.appscriptify.com/api

Installation

pip install appscriptify-botlink

Quickstart (Python)

Example usage to create a client, pick a project and chat with its agent:

from botlink import Botlink

botlink = Botlink(api_key="as-key-YOUR-API-KEY")
project = botlink.projects["40a23cefde0400baf43453fdac387d99"]
agent = project.agent
response = agent.chat(message="Hello")
print(response)

Client: Botlink

Construct the client with your API key:

Botlink(api_key: str)

- Returns: a `Botlink` client instance exposing a `projects` registry. - Behaviour: on initialization the client validates the provided API key by calling the server endpoint /api/sdk/validate/key. The call returns JSON used to populate the list of project IDs the key has access to. - Errors: a missing API key raises ValueError. If the server responds with an HTTP error the client raises RuntimeError. If the server indicates the key is invalid the client raises ValueError with the server-provided reason.

Validation endpoint

POST /api/sdk/validate/key
Request JSON: {"api_key": ""}
Response JSON: {
  "valid": true|false,
  "reason": "optional message when invalid",
  "projects": ["project_id_1", "project_id_2", ...]
}

Projects: `projects` (ProjectRegistry)

The client exposes `projects`, a lazy registry object. The registry holds the list of project IDs returned during API key validation and only creates a `Project` instance when a project ID is accessed.

Access: `botlink.projects[project_id]` returns a `Project` instance.
List: `botlink.projects.list()` returns the list of available project IDs (list of strings).
Contains: `project_id in botlink.projects` returns a boolean.

Project object

When a `Project` is created the SDK fetches project information from the server and exposes a small set of attributes and helper methods.

Project properties (read-only):
  project_id: str        # the project's id (as passed when accessing the registry)
  name: str | None       # server-provided project name (key: "project_name")
  as_key: str | None     # server-provided as_key (key: "as_key")
  authorised_domains: str | None  # server-provided authorised domains (key: "authorised_domain")
  agent: Agent           # Agent instance attached to this project

- Returns / behaviour: the project constructor issues a POST to /api/sdk/project/info with the `api_key` and `project_id` and expects JSON containing at least the keys above. If the request fails the constructor raises RuntimeError.

Project methods

__repr__: returns a compact string representation showing `project_id`, `name`, `as_key`, and `authorised_domains` (all values double-quoted in the representation).
greet(): returns a string greeting of the form Hello from project <project_id>.

Project info endpoint

POST /api/sdk/project/info
Request JSON: {"api_key": "", "project_id": ""}
Response JSON: {
  "project_name": "...",
  "as_key": "...",
  "authorised_domain": "...",
  ...
}

Agent object

Each `Project` exposes an `agent` property which is an `Agent` instance. The agent fetches metadata about the conversational bot and provides a synchronous `chat` method.

Agent properties (read-only):
  project_id: str
  bot_name: str | None
  bot_description: str | None
  instructions: str | None
  temperature: float | None
  welcome_message: str | None

Agent.chat

Sends a chat message to the project's agent and returns the server's JSON response.

response = agent.chat(
  message: str,
  history: list | None = None,
  temperature: float | None = None,
  instructions: str | None = None,
  max_tokens: int | None = None
)

- Parameters: - message (str, required): the user's input message. - history (list, optional): previous conversation turns (format is passed through to the API as-is). - temperature (float, optional): override the agent's temperature for this request. - instructions (str, optional): additional instructions for this chat call. - max_tokens (int, optional): limit response token length for the server. - Returns: a dict containing the JSON body returned by the server for the chat endpoint. The SDK does not impose a schema — the returned dict is whatever the server sends back. Typical keys include reply text, metadata and conversation identifiers, but those are server-specific. - Errors: if the HTTP response is not OK the method raises RuntimeError.

Agent chat endpoint

POST /api/sdk/agent/chat
Request JSON: {
  "api_key": "",
  "project_id": "",
  "message": "...",
  "history": [...],
  "temperature": 0.7,
  "instructions": "...",
  "max_tokens": 256
}
Response JSON: {...}  # JSON object representing the chat response

Error handling & timeouts

- Network timeouts are applied to all outgoing requests (default: 20 seconds unless overridden by the SDK). Specific timeouts used by calls are visible in the SDK (`DEFAULT_TIMEOUT` / per-call value). - Non-2xx HTTP responses from the server raise RuntimeError with the HTTP status code included in the message. - Missing or invalid API keys raise ValueError with a server-provided reason when available.

Server endpoints used by the SDK

/api/sdk/validate/key — validates API key; returns whether key is valid and the list of accessible projects.
/api/sdk/project/info — returns project metadata such as `project_name`, `as_key` and `authorised_domain`.
/api/sdk/agent/info — returns agent metadata such as `bot_name`, `bot_description`, `instructions`, `temperature`, and `welcome_message`.
/api/sdk/agent/chat — sends a chat request and returns the agent's response JSON.

Notes & best practices

Keep your API key secret; pass it to Botlink(...) or set it in the BOTLINK_API_KEY environment variable.
The SDK performs synchronous HTTP requests. For high-throughput or latency-sensitive usage consider running multiple threads or an async wrapper around the SDK.
Because the SDK returns raw server JSON for chat calls, consult your server's API docs (server-side) for exact chat response fields and formats.

Troubleshooting

If you receive ValueError: Invalid API key, confirm the API key was copied correctly and that it hasn't expired or been revoked.
If you receive RuntimeError with an HTTP status code, inspect the server logs or the server's error message; common causes are malformed request payloads or missing permissions for the project.

Botlink Docs