# Aigently API

> Place calls, start chats and read every conversation from your own server.

Your agents already answer phones, talk on your website and chat on WhatsApp. The API lets your own
systems take part: place a call when a lead arrives, give an inbound caller's details to the agent
before it says hello, run a chat from your app, and read back the transcript, the analysis and the
recording of every conversation.

## Start here

- **[Quickstart](/quickstart)** — a test key, a test call that rings nobody, its transcript, and its
  webhooks on your laptop, in about twenty minutes.
- **[API reference](/reference)** — every operation, with an example in seven languages and a
  *Try it* that takes a test key.
- **[Test mode](/guides/test-mode)** — everything you can do without a phone number or credit.

## How it works

- **Address.** `https://api.aigently.ai/v1`. A company running its own copy of Aigently uses its
  own address with `/v1` on the end.
- **Keys.** An organization API key in `Authorization: Bearer <key>`. Keys are made on the
  console's *API keys* page. A test key (`ag_test_…`) sees only test data and never rings a real
  phone; a live key (`ag_live_…`) places real calls. See [API keys](/guides/keys).
- **JSON**, with `snake_case` fields. Unknown fields in a request are refused, so a typo fails
  loudly. Responses may gain fields at any time; read the ones you know.
- **Errors** are problem documents with a stable `code` — see [Errors](/errors).
- **Retries are safe** where they matter: a call needs an `Idempotency-Key`, and sending the same
  request again returns the same conversation. See [Safe retries](/guides/idempotency).

**curl**

```sh
#!/bin/sh
# Check your key
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/me" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"
```

**JavaScript**

```js
// Check your key
const response = await fetch("https://api.aigently.ai/v1/me", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`,
  },
});
const answer = await response.json();
if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`);
console.log(answer);
```

**Python**

```python
# Check your key
# pip install httpx
import os

import httpx

response = httpx.get(
    "https://api.aigently.ai/v1/me",
    headers={
        "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}",
    },
)
if response.is_error:
    raise SystemExit(response.text)
print(response.json())
```

**Go**

```go
// Check your key
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/me", nil)
	if err != nil {
		panic(err)
	}
	request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY"))
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()
	body, _ := io.ReadAll(response.Body)
	if response.StatusCode >= 400 {
		fmt.Fprintln(os.Stderr, string(body))
		os.Exit(1)
	}
	fmt.Println(string(body))
}
```

**Java**

```java
// Check your key
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Main {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/me"))
            .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY"))
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();
        // HTTP/1.1: on a plain-http address Java's default asks to upgrade, which not every
        // server allows.
        HttpClient client = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build();
        HttpResponse<String> response =
            client.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            System.err.println(response.body());
            System.exit(1);
        }
        System.out.println(response.body());
    }
}
```

**C#**

```csharp
// Check your key
using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("AIGENTLY_API_KEY"));
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.aigently.ai/v1/me")
{
};
var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
{
    Console.Error.WriteLine(body);
    return 1;
}
Console.WriteLine(body);
return 0;
```

**PHP**

```php
<?php
// Check your key
$curl = curl_init("https://api.aigently.ai/v1/me");
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"),
    ],
]);
$body = curl_exec($curl);
if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) {
    fwrite(STDERR, $body . "\n");
    exit(1);
}
echo $body, "\n";
```

## Examples in your language

Every example on this site is in curl, JavaScript, Python, Go, Java, C# and PHP, using each
language's usual HTTP tool — there is nothing of ours to install. Pick a language once and every
example follows. Every example is run against the platform before it is published.

## Downloads

- [The OpenAPI file](/openapi.v1.json) — the whole API, for code generators and your own tools.
- [A Postman collection](/aigently.postman_collection.json), which Bruno and Insomnia import too.
- [`aigently.mjs`](/aigently.mjs) — the command line: every operation, an agent's fields as
  types, `listen` and `mcp`. See [the command line](/cli).
- [`llms.txt`](/llms.txt) and [`llms-full.txt`](/llms-full.txt) for AI coding tools. Every page
  is also available as Markdown: add `.md` to its address.