Using the AIRA API from R and Python

AIRA is the AI service of the Aridhia DRE. It provides governed large language model inference as part of the platform, which means applications and scripts running inside a workspace can send prompts to a model without workspace data being passed to an external AI provider.

AIRA is exposed to workspaces through an API that follows the widely used OpenAI chat completions convention. Any client library that can talk to an OpenAI compatible endpoint can talk to AIRA. This article shows how to make calls from R and from Python, and covers the practical points to be aware of when building AIRA into an application.

Before you start

You will need the following:

  • AIRA enabled for your workspace, with a model deployment. AIRA is enabled per workspace, and within it your administrator configures a deployment for each model you want to use. When you make a request you pass the deployment name as the model name. Some API clients require a slightly different format, in which case use aridhia/<deployment_name>. If you are not sure whether AIRA is enabled, or which deployment name to use, contact your workspace administrator.
  • The AIRA base URL for your deployment. The examples in this article use the UK South SaaS endpoint. The URL differs between regions and deployments, so confirm the correct one for your tenant with your administrator.
  • The WORKSPACE_API_KEY environment variable. The platform makes this available inside the workspace, and it authenticates your calls to AIRA. You do not need to create or manage a key yourself.
  • A client library, installed in your workspace in the normal way. The examples below use ellmer for R and openai for Python, but these are examples rather than requirements; any OpenAI compatible client will work, as will plain HTTP.

Connection details

The examples throughout this article use the following values:

Setting Value
Base URL https://api.uksouth.saas.aridhia.io/api/aira/v1
Model (deployment name) workspace-chat
Authentication Bearer token, taken from WORKSPACE_API_KEY

Before writing any application code, it is worth confirming the endpoint, key, and model name from a workspace terminal:

curl -s "https://api.uksouth.saas.aridhia.io/api/aira/v1/chat/completions" \
  -H "Authorization: Bearer $WORKSPACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "workspace-chat",
    "messages": [{"role": "user", "content": "Reply with the single word: ready"}]
  }'

A successful call returns a JSON document whose choices array contains the model's reply. If this works, everything below will too.

Calling AIRA from R

The ellmer package provides a convenient chat client for OpenAI compatible endpoints. Point it at the AIRA base URL and pass the workspace key:

library(ellmer)

chat <- chat_openai(
  base_url = "https://api.uksouth.saas.aridhia.io/api/aira/v1",
  model    = "workspace-chat",
  api_key  = Sys.getenv("WORKSPACE_API_KEY")
)

chat$chat("Suggest three data quality checks for a CSV of clinical measurements.")

The chat object keeps the conversation history, so further chat$chat() calls continue the same conversation. Create a new client when you want to start fresh, and use the system_prompt argument of chat_openai() to give the model standing instructions.

When AIRA is called from an application rather than interactively, wrap every call in tryCatch() and treat failure as a normal outcome, so the application keeps working if the service is slow or temporarily unavailable:

reply <- tryCatch(
  chat$chat("Summarise the structure of the attached findings."),
  error = function(e) {
    message("AIRA call failed: ", conditionMessage(e))
    NULL
  }
)

Calling AIRA from Python

The openai package works unchanged once its base URL is pointed at AIRA:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.uksouth.saas.aridhia.io/api/aira/v1",
    api_key=os.environ["WORKSPACE_API_KEY"],
)

response = client.chat.completions.create(
    model="workspace-chat",
    messages=[
        {"role": "user", "content": "Suggest three data quality checks for a CSV of clinical measurements."},
    ],
    timeout=60,
)

print(response.choices[0].message.content)

If you prefer not to add a dependency, the standard library plus requests is enough, because the API is plain HTTP with JSON:

import os
import requests

resp = requests.post(
    "https://api.uksouth.saas.aridhia.io/api/aira/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['WORKSPACE_API_KEY']}"},
    json={
        "model": "workspace-chat",
        "messages": [{"role": "user", "content": "Reply with the single word: ready"}],
    },
    timeout=60,
)
resp.raise_for_status()
print(resp.json()["choices"][0]["message"]["content"])

Building AIRA into an application

A few practical points from production use of the API:

Set explicit timeouts and expect variable latency. A short prompt typically returns in a few seconds, but large prompts or long structured outputs can take considerably longer. Choose a timeout appropriate to the call, and make sure your application handles a timeout gracefully rather than hanging or crashing.

Do not block the user interface. If your application makes AIRA calls per file across a batch, or makes any call the user has to wait on, run the calls asynchronously and update the interface when results arrive. The application should remain fully usable while calls are in flight, and should remain fully usable if AIRA is unavailable altogether.

Parse structured output defensively. If you ask the model to reply with JSON, state in the prompt that it should return JSON only, with no surrounding prose. Some models still wrap the JSON in markdown code fences, so strip any leading and trailing fence markers before parsing, and validate the parsed structure before using it.

Consider disabling thinking mode for structured output. Reasoning capable models can spend most of their response time on internal reasoning before producing the answer. For prompts that require a fixed JSON schema this adds little quality but a great deal of latency, and it can be switched off through a request parameter. In R with ellmer:

chat <- chat_openai_compatible(
  base_url = "https://api.uksouth.saas.aridhia.io/api/aira/v1",
  model    = "workspace-chat",
  api_key  = Sys.getenv("WORKSPACE_API_KEY"),
  api_args = list(chat_template_kwargs = list(enable_thinking = FALSE))
)

In Python, the openai client passes the same parameter through extra_body:

response = client.chat.completions.create(
    model="workspace-chat",
    messages=[{"role": "user", "content": "..."}],
    extra_body={"chat_template_kwargs": {"enable_thinking": False}},
)

chat_openai_compatible() is ellmer's generic constructor for OpenAI compatible services and takes the same connection details as chat_openai(). If your client library version rejects the extra parameter, construct the client without it; the call will still work, just with thinking enabled.

Data governance

Because AIRA runs as part of the platform, prompts and responses are processed within the DRE rather than being sent to an external AI provider. This is what makes it appropriate to use AIRA with workspace data, subject to the terms that apply to your project.

Everything else about workspace governance is unchanged. Content generated by AIRA and saved to files is workspace content like any other, and taking it out of the workspace goes through the normal airlock process.

Troubleshooting

Authentication errors (401 or 403). Check that WORKSPACE_API_KEY is set in the session making the call, for example with Sys.getenv("WORKSPACE_API_KEY") in R or echo $WORKSPACE_API_KEY in a terminal. If it is not set, contact your workspace administrator.

Connection failures. If the endpoint cannot be reached, AIRA may not be enabled for your workspace, or the base URL may not be the correct one for your deployment. Your administrator can confirm both.

Timeouts on large prompts. Reduce the amount of content in the prompt, extend the client timeout, and for structured output disable thinking mode as described above.

If AIRA does not appear to be available in your workspace, or you need the endpoint details for your deployment, contact your platform administrator or the Service Desk.

Updated on July 31, 2026
Back to top