Telara API Reference

Introduction

Welcome to the Telara API Reference. This documentation covers all REST API endpoints for interacting with Telara's AI agent platform. Our API is RESTful, returns JSON responses, and uses standard HTTP response codes.

Authentication

Telara uses API keys to authenticate requests. Include your API key in the Authorization header of every request.

curl https://api.telara.com/v1/agent-definitions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json"

Getting Started

curl -X POST https://api.telara.com/v1/agent-definitions/$AGENT_DEFINITION_ID/invoke \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "input": "Summarise the open incidents for the payments service"
    }'

{
    "execution_id": "exec_abc123",
    "agent_definition_id": "def_incident_responder",
    "status": "running",
    "created_at": "2024-10-09T10:30:00Z"
  }

curl https://api.telara.com/v1/agent-executions/$EXECUTION_ID \
    -H "Authorization: Bearer YOUR_API_KEY"

Agents API

Agents are addressed as definitions; invoking one starts an execution. Endpoints below are transcribed from the Gateway HTTP contract (telara-proto gateway.proto), with the proto line cited so it can be re-verified.

curl -X POST https://api.telara.com/v1/agent-definitions/$AGENT_DEFINITION_ID/invoke \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "input": "Summarise the open incidents for the payments service"
    }'

{
    "execution_id": "exec_abc123",
    "agent_definition_id": "def_incident_responder",
    "status": "running",
    "created_at": "2024-10-09T10:30:00Z"
  }

curl https://api.telara.com/v1/agent-executions/$EXECUTION_ID \
    -H "Authorization: Bearer YOUR_API_KEY"

{
    "execution_id": "exec_abc123",
    "agent_definition_id": "def_incident_responder",
    "status": "completed",
    "created_at": "2024-10-09T10:30:00Z",
    "completed_at": "2024-10-09T10:32:15Z"
  }

Webhooks

Set up webhooks to receive real-time notifications when agents execute.

Rate Limits

X-RateLimit-Limit: 10000
  X-RateLimit-Remaining: 9850
  X-RateLimit-Reset: 1696680896

Error Handling

{
    "error": {
      "code": "invalid_request",
      "message": "The 'repository' parameter is required",
      "param": "repository",
      "type": "validation_error"
    },
    "request_id": "req_abc123"
  }

SDKs & Libraries

import os, requests

resp = requests.post(
    "https://api.telara.com/v1/agent-definitions/{AGENT_DEFINITION_ID}/invoke",
    headers={"Authorization": f"Bearer {os.environ['TELARA_API_KEY']}"},
    json={"input": "Summarise the open incidents for the payments service"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

const res = await fetch(
  `https://api.telara.com/v1/agent-definitions/${agentDefinitionId}/invoke`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.TELARA_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      input: 'Summarise the open incidents for the payments service',
    }),
  },
);
if (!res.ok) throw new Error(await res.text());
console.log(await res.json());

Gateway Endpoints

The Telara Gateway provides a unified API surface for all platform functionality, including authentication, user management, agents, integrations, search, and more. The endpoint groups below cover the surfaces available to API clients.