# 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 `. 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 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 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. --- # Quickstart > A test call that rings nobody, its transcript and analysis, then its webhooks and a test inbound call on your own machine. In the first ten minutes you place a test call and read what happened. In the next ten you receive its webhooks on your laptop and make a test call to an agent that asks your own server who is calling. Nothing here rings a phone or spends credit. ## 1. Make a test key In the console, open **API keys** and choose **New API key**. Pick **Test** and the *Outbound calling* preset, then **Create key**. The key is shown once: keep it in your environment. ```sh export AIGENTLY_API_KEY=ag_test_... ``` ## 2. Make an agent Make an agent from a template — *Appointment reminder* places calls, *Receptionist* answers them — and **Publish** it. Its id is on **Connect → Server API**, with the fields a request can fill in. Or ask the API for your agents: **curl** ```sh #!/bin/sh # List agents curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/agents?limit=20" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List agents const response = await fetch("https://api.aigently.ai/v1/agents?limit=20", { 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 # List agents # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/agents", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "limit": 20, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List agents package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/agents?limit=20", 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 // List agents 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/agents?limit=20")) .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 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 // List agents 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/agents?limit=20") { }; 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 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"; ``` ## 3. Place a test call A test key calls only [test numbers](/guides/test-mode#test-numbers). `+12025550100` answers, talks for a few seconds and hangs up — with the agent's real greeting and your values in it. **curl** ```sh #!/bin/sh # Place a call. With a test key this calls a test number and rings nobody. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/calls" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ -H "Idempotency-Key: lead-20931" \ --json '{ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" }' ``` **JavaScript** ```js // Place a call. With a test key this calls a test number and rings nobody. const response = await fetch("https://api.aigently.ai/v1/calls", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "lead-20931", }, body: JSON.stringify({ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Place a call. With a test key this calls a test number and rings nobody. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/calls", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", "Idempotency-Key": "lead-20931", }, json={ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "variables": { "first_name": "Sara", }, "metadata": { "crm_lead_id": "L-20931", }, "external_id": "lead-20931", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Place a call. With a test key this calls a test number and rings nobody. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/calls", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") request.Header.Set("Idempotency-Key", "lead-20931") 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 // Place a call. With a test key this calls a test number and rings nobody. 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 { String body = """ { "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/calls")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .header("Idempotency-Key", "lead-20931") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Place a call. With a test key this calls a test number and rings nobody. 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.Post, "https://api.aigently.ai/v1/calls") { Content = new StringContent( """ { "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" } """, Encoding.UTF8, "application/json"), }; request.Headers.Add("Idempotency-Key", "lead-20931"); 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", "Idempotency-Key: lead-20931", ], CURLOPT_POSTFIELDS => json_encode([ "agent_id" => "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number" => "+12025550100", "variables" => [ "first_name" => "Sara", ], "metadata" => [ "crm_lead_id" => "L-20931", ], "external_id" => "lead-20931", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` Send a value for each field your agent needs: its `variables_schema` lists them, and the agent's **Server API** tab shows this request with its own fields already filled in. The answer is the conversation, `pending` until the test number answers. The `Idempotency-Key` is your own id for this call: send the same request again and you get the same conversation back instead of a second call. ## 4. Read what happened About ten seconds later the call has ended. Read it with its transcript: **curl** ```sh #!/bin/sh # Read a conversation with its transcript curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read a conversation with its transcript const response = await fetch("https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript", { 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 # Read a conversation with its transcript # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "include": "transcript", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read a conversation with its transcript package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript", 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 // Read a conversation with its transcript 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript")) .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 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 // Read a conversation with its transcript 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript") { }; 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 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"; ``` `status` is `completed`, `disposition` is `answered`, and `transcript.entries` holds what was said. Where the agent analyses its calls, `analysis` carries the outcome and the checks. A test call also has a short sample recording: **curl** ```sh #!/bin/sh # Get a link to a recording. The link works for five minutes, so download the audio straight away. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Get a link to a recording. The link works for five minutes, so download the audio straight away. const response = await fetch("https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording", { 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 # Get a link to a recording. The link works for five minutes, so download the audio straight away. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Get a link to a recording. The link works for five minutes, so download the audio straight away. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording", 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 // Get a link to a recording. The link works for five minutes, so download the audio straight away. 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording")) .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 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 // Get a link to a recording. The link works for five minutes, so download the audio straight away. 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording") { }; 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 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"; ``` ## 5. Receive its webhooks on your laptop The platform cannot reach `localhost`, so [`aigently listen`](/cli) keeps a connection open with your test key and passes each test event to a server on your machine. It needs only Node.js 22. ```sh curl -O https://developers.aigently.ai/aigently.mjs node aigently.mjs listen --forward-to localhost:3000/hooks ``` It prints a signing secret. Place another test call and your server receives `conversation.started`, `conversation.ended`, `conversation.analyzed` and `conversation.recording_ready`, signed with that secret. Check each one with the [webhook helper](/guides/webhooks#check-the-signature) before you trust it. ## 6. Make a test call to your agent Give your inbound agent a lookup address under **Connect → Phone → Look up who is calling**, then forward test lookups to your own server too: ```sh node aigently.mjs listen --forward-to localhost:3000/hooks --forward-lookups-to localhost:3000/lookup ``` Your `/lookup` answers with values for the agent's fields: ```json {"variables": {"first_name": "Sara"}, "metadata": {"crm_id": "C-1042"}} ``` Now call the agent from a test number: **curl** ```sh #!/bin/sh # Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/test/inbound-calls" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" }' ``` **JavaScript** ```js // Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. const response = await fetch("https://api.aigently.ai/v1/test/inbound-calls", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/test/inbound-calls", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/test/inbound-calls", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. 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 { String body = """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/test/inbound-calls")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. 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.Post, "https://api.aigently.ai/v1/test/inbound-calls") { Content = new StringContent( """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "agent_id" => "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number" => "+12025550100", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` The answer says where the values came from (`listen`, here) and the greeting they produced. See [Inbound calls](/guides/inbound-calls) for everything the lookup is sent and may answer. ## Next - [Going live](/going-live) — what changes with a live key. - [Variables](/guides/variables) — how an agent's fields are filled, checked and kept safe. - [Chat and streaming](/guides/chat) — the same agents, from your app. --- # Going live > What changes when the same code runs with a live key. The code you wrote against a test key is the code you run live: the address, the requests and the answers are the same. What changes is that calls ring real phones, conversations cost credit, and your receivers hear about real people. ## Before the first live call - **A live key.** On **API keys**, make one with **Live**, limited to the projects — or the agents — it needs. Asking for it takes your password again, and every owner of the organization is emailed. A live key never works from a browser: keep it on your server. - **A number to call from.** An agent that calls out needs a verified number on its **Connect → Caller ID** tab. Without one, a call is refused with `caller_id_unavailable`. - **Countries.** The deployment calls only the countries it allows, never emergency or service numbers, and premium-rate numbers only where it has said so. Anything else is refused with `destination_not_allowed`. Send numbers in full international format: `+`, the country code, then the number. - **Consent.** Call people who agreed to hear from you, at hours that suit them. The platform records who placed every call — the key's name is on it in the audit log. - **Live receivers.** A webhook receiver is either live or test. Add a live one for your production server; your test receivers keep getting test events only. ## Limits | Limit | Default | When it is reached | |---|---|---| | Calls at the same time, per organization | 10 | `429 concurrency_limit_reached` | | Calls a day, per organization | 2,000 | `429 daily_limit_reached` | | Requests a minute, per key | 600 reads, 120 writes, 1,200 chat messages | `429 rate_limited` | `GET /v1/me` shows your key's limits and how many of your calls are in progress. Our staff can raise an organization's limits. See [Rate limits](/guides/rate-limits). **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 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 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"; ``` ## Credit Live conversations are charged from the organization's credit, as conversations from the console are; the API itself costs nothing. When the credit runs out, new calls and chats are refused with `402 insufficient_credit`, and reading conversations keeps working. ## Keep it safe - Rotate a key that may have leaked — the old secret keeps working for the time you choose, so your servers can be updated first. Revoke a key nobody uses. - Check every webhook's signature before you act on it ([how](/guides/webhooks#check-the-signature)). - Build each call's `Idempotency-Key` from your own data, so a retry can never call twice. --- # The command line > Every API operation from a terminal, an agent's fields as types, test events on your own machine, and MCP over standard input. One file, and it needs only Node.js 22 or later: ```sh curl -O https://developers.aigently.ai/aigently.mjs export AIGENTLY_API_KEY=ag_test_... node aigently.mjs conversations list --limit 5 ``` ## Any API operation Every operation in the [reference](/reference) is a command: its resource, its method, its ids in order, and its fields as flags — the field's name with dashes. ```sh node aigently.mjs agents retrieve 8a1f3c2e-… node aigently.mjs conversations retrieve 5f0c9a52-… --include transcript node aigently.mjs calls create --agent-id 8a1f3c2e-… --to-number +966501234567 \ --variables '{"first_name": "Sara"}' node aigently.mjs conversations list --agent-id 8a1f3c2e-… --all > conversations.jsonl ``` - **Lists take commas** (`--include transcript,cost`), or a JSON array when an item has a comma in it (`--turns '["Hi, are you open on Sunday?"]'`). **Objects take JSON**, and a file takes its path (`--file ./faq.pdf`). `null` sends null, which is how a number is detached from its agent. - `--json '{…}'`, or `--json @body.json`, sends a whole body; flags add to it. - **`--all` walks every page of a list**, printing one JSON object a line. - **A request that takes an `Idempotency-Key` gets one**, unless you pass your own with `--idempotency-key`. - The answer is printed as JSON. A refusal prints its `code`, `detail` and request id, and exits 1. `node aigently.mjs operations` lists every command. ## An agent's fields as types ```sh node aigently.mjs types --agent 8a1f3c2e-… > agent.ts node aigently.mjs types --agent 8a1f3c2e-… --lang python > agent_fields.py ``` It writes the agent's [three lists of fields](/guides/variables) — what a conversation can start with, what it collects, and what its analysis writes — as TypeScript interfaces or Python `TypedDict`s, required fields marked. Write them again when the agent's fields change: the `agent.updated` event says when. A field named like a Python keyword, such as `from`, is written in the `TypedDict("…", {…})` form, which takes any name. ## Evaluations in a build step: `evaluate` ```sh node aigently.mjs evaluate 8a1f3c2e-… ``` It rehearses the agent's saved conversations, waits for the verdict, prints every conversation's outcome, and exits `0` when all passed, `1` when one failed, and `3` when none failed but some could not be checked. `--json` prints the whole run instead, and `--timeout` says how many seconds to wait (25 minutes unless you say). See [Evaluations in your pipeline](/guides/evaluations). ## A call, followed live: `follow` ```sh node aigently.mjs follow 5f0c9a52-… ``` It prints what is said on a call as it is said — `Caller:` and `Agent:` lines — and stops when the call ends. `--json` prints each line as the API sends it. See [Live calls](/guides/live-calls). ## Test events on your machine: `listen` The platform cannot reach `localhost`. `listen` keeps a connection open to the API with a **test key** and passes on everything a test webhook receiver would be sent — and, if you ask, the context lookups of test calls — to a server on your machine. ```sh node aigently.mjs listen --forward-to localhost:3000/hooks ``` - **Events.** Each test event is POSTed to `--forward-to` with the headers a webhook carries, signed with the session's own secret, which it prints when the connection is ready. Check them exactly as you would a receiver's ([how](/guides/webhooks#check-the-signature)). What your server answers is only printed. - **Lookups.** With `--forward-lookups-to`, a test call's context lookup is POSTed there, and your server's status and body go back to the call as its answer — so a [test inbound call](/guides/inbound-calls#in-test-mode) reaches your own code. An open session is asked before the agent's test address or its sample answer. - **Only what the key reaches.** A key limited to some projects or agents hears only about those, and is asked only their test calls' lookups. - **Only what the key may read.** Listening needs `conversations:read`, and a `conversation.transcript` event also needs `transcripts:read`. Every key preset has both. - **Test keys only.** A live key is refused when it connects: real conversations go to receivers whose addresses have been checked, never to a laptop. - **A few at a time.** A key may keep 3 sessions open, and an organization 10. - **It stops when the key does.** Revoke the key, let it expire, or rotate it without an overlap, and the session ends within half a minute. - **Stop it and its session is gone**, with everything it was holding: the next test call's events go only to your test receivers. ## An AI assistant: `mcp` `node aigently.mjs mcp` carries an assistant's [MCP](/guides/mcp) messages from standard input to the API's MCP server, and the answers back — for an assistant that runs its tools as a local program. ## Options | Option | What it does | |---|---| | `--api-key ` | Your key. Or set `AIGENTLY_API_KEY`. | | `--api ` | The API's address, for a company running its own copy. Or set `AIGENTLY_BASE_URL`. Default `https://api.aigently.ai`. | | `--all` | For a list: every page, one JSON object a line. | | `--idempotency-key ` | Your own id for a request that takes one. | | `--forward-to ` | `listen`: where to POST each test event, like `localhost:3000/hooks`. | | `--forward-lookups-to ` | `listen`: where to POST each test call's lookup. | | `--help` | The options. | Your key travels in a header, never in an address, where a proxy would log it. --- # Outbound calls > Place a call with an agent, follow it, end it, and know what each ending means. An outbound agent calls a number you give it, with values you give it, and you hear about every step. A call needs the `calls:write` permission. ## Place a call **curl** ```sh #!/bin/sh # Place a call. With a test key this calls a test number and rings nobody. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/calls" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ -H "Idempotency-Key: lead-20931" \ --json '{ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" }' ``` **JavaScript** ```js // Place a call. With a test key this calls a test number and rings nobody. const response = await fetch("https://api.aigently.ai/v1/calls", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "lead-20931", }, body: JSON.stringify({ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Place a call. With a test key this calls a test number and rings nobody. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/calls", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", "Idempotency-Key": "lead-20931", }, json={ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "variables": { "first_name": "Sara", }, "metadata": { "crm_lead_id": "L-20931", }, "external_id": "lead-20931", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Place a call. With a test key this calls a test number and rings nobody. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/calls", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") request.Header.Set("Idempotency-Key", "lead-20931") 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 // Place a call. With a test key this calls a test number and rings nobody. 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 { String body = """ { "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/calls")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .header("Idempotency-Key", "lead-20931") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Place a call. With a test key this calls a test number and rings nobody. 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.Post, "https://api.aigently.ai/v1/calls") { Content = new StringContent( """ { "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" } """, Encoding.UTF8, "application/json"), }; request.Headers.Add("Idempotency-Key", "lead-20931"); 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", "Idempotency-Key: lead-20931", ], CURLOPT_POSTFIELDS => json_encode([ "agent_id" => "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number" => "+12025550100", "variables" => [ "first_name" => "Sara", ], "metadata" => [ "crm_lead_id" => "L-20931", ], "external_id" => "lead-20931", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` | Field | What it is | |---|---| | `agent_id` | One of your outbound agents. It must be published. | | `to_number` | International format: `+`, the country code, then the number. | | `variables` | Values for the agent's fields — see [Variables](/guides/variables). | | `metadata` | Your own data, up to 20 keys. The agent never sees it; you get it back on every read and every event. | | `external_id` | Your own id for the conversation — a lead, an order. Find it again with `GET /v1/conversations?external_id=`. | | `from_number` or `phone_number_id` | Which of the agent's numbers to call from. Leave both out and the agent's own caller ID is used. | | `language` | One of the agent's language versions, like `ar`. | | `call_window` | The hours the call may start in — see [Calling hours](#calling-hours). | **`Idempotency-Key` is required.** It is your own id for this call, up to 120 characters — build it from your data, like `lead-8812-attempt-2`. The same request with the same key returns the same conversation, with `Idempotent-Replayed: true`, and never calls twice; the same key with a different request is refused with `idempotency_key_reused`. See [Safe retries](/guides/idempotency). The answer is `201` with the [conversation](/reference/objects/Conversation), `pending` until the phone is answered. Everything a call can be refused for is checked before anything is dialled. ## Follow it Either listen for [webhooks](/guides/webhooks) — `conversation.started` when it is answered and `conversation.ended` exactly once when it ends, answered or not — or read the conversation: **curl** ```sh #!/bin/sh # Read a conversation with its transcript curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read a conversation with its transcript const response = await fetch("https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript", { 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 # Read a conversation with its transcript # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "include": "transcript", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read a conversation with its transcript package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript", 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 // Read a conversation with its transcript 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript")) .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 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 // Read a conversation with its transcript 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript") { }; 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 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"; ``` `status` is `pending`, then `active` once answered, and finally `completed` or `failed`. The `revision` only goes up, so of two copies of a conversation the higher one is the newer. ## How a call ends Every way a call can end, what the conversation says about it, and which events you get: | What happened | `status` | `disposition` | `ended_by` | Events | Call again? | |---|---|---|---|---|---| | Answered, talked, and somebody hung up | `completed` | `answered` | `caller` or `agent` | `conversation.started`, `conversation.ended`, `conversation.analyzed`, `conversation.recording_ready` | No. | | Ended with /end after it was answered | `completed` | `answered` | `api` | `conversation.started`, `conversation.ended`, `conversation.analyzed` | No. | | An answering machine answered, and the agent left its message | `completed` | `voicemail_left` | `agent` | `conversation.started`, `conversation.ended` | Your choice. | | An answering machine answered, and no message was left | `failed` | `voicemail` | null | `conversation.started`, `conversation.ended` | Yes, later. | | The line was busy | `failed` | `busy` | null | `conversation.ended` | Yes, later. | | It rang and nobody answered | `failed` | `no_answer` | null | `conversation.ended` | Yes, later. | | The person rejected the call | `failed` | `declined` | null | `conversation.ended` | Usually not. | | The carrier would not put the call through | `failed` | `unreachable` | `failure` | `conversation.ended` | Check the number first. | | The call could not be placed at all | `failed` | — | `failure` | `conversation.ended` | Yes, in a moment. | | Cancelled with /end while it was ringing | `failed` | `no_answer` | `api` | `conversation.ended` | No — you cancelled it. | | Marked failed when its report was late, then reported as a full conversation | `completed` | `answered` | `caller` or `agent` | `conversation.started`, `conversation.ended`, `conversation.updated`, `conversation.analyzed` | No — always keep the highest revision. | - `conversation.analyzed` arrives only for an agent that analyses its conversations, and a little after the end. - `conversation.recording_ready` arrives only for a call that was recorded. - Events can arrive out of order. Keep the one with the highest `revision`. An answering machine is handled by the agent's own voicemail setting: it leaves its message, or hangs up and the call ends `voicemail`. ## End it yourself **curl** ```sh #!/bin/sh # End a call or a chat curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/end" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // End a call or a chat const response = await fetch("https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/end", { method: "POST", 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 # End a call or a chat # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/end", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // End a call or a chat package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/end", 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 // End a call or a chat 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/end")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("POST", 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 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 // End a call or a chat 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.Post, "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/end") { }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => "", ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` A call still ringing is cancelled; one in progress ends with the agent's own goodbye. Ending always answers `200` with the conversation, so it is safe to send again. ## Calling hours Name the hours a call may start in, in the time zone of the person you are calling: ```json "call_window": { "timezone": "America/New_York", "start": "09:00", "end": "17:00", "days": ["mon", "tue", "wed", "thu", "fri"] } ``` `timezone` is a name like `Asia/Riyadh`. The window includes `start` and ends just before `end`. Leave `days` out for every day of the week. A call sent outside its window is refused with `outside_call_window`, and `detail` says when the window opens next — so schedule it for then. ## Schedule a call for later **curl** ```sh #!/bin/sh # Schedule a call inside calling hours. It is placed at the first moment the window is open at or after dial_at. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/scheduled-calls" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ -H "Idempotency-Key: reminder-20931" \ --json '{ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "dial_at": "2026-10-12T13:00:00Z", "call_window": { "timezone": "America/New_York", "start": "09:00", "end": "17:00", "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "variables": { "first_name": "Sara" }, "external_id": "reminder-20931" }' ``` **JavaScript** ```js // Schedule a call inside calling hours. It is placed at the first moment the window is open at or after dial_at. const response = await fetch("https://api.aigently.ai/v1/scheduled-calls", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "reminder-20931", }, body: JSON.stringify({ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "dial_at": "2026-10-12T13:00:00Z", "call_window": { "timezone": "America/New_York", "start": "09:00", "end": "17:00", "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "variables": { "first_name": "Sara" }, "external_id": "reminder-20931" }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Schedule a call inside calling hours. It is placed at the first moment the window is open at or after dial_at. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/scheduled-calls", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", "Idempotency-Key": "reminder-20931", }, json={ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "dial_at": "2026-10-12T13:00:00Z", "call_window": { "timezone": "America/New_York", "start": "09:00", "end": "17:00", "days": ["mon", "tue", "wed", "thu", "fri"], }, "variables": { "first_name": "Sara", }, "external_id": "reminder-20931", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Schedule a call inside calling hours. It is placed at the first moment the window is open at or after dial_at. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "dial_at": "2026-10-12T13:00:00Z", "call_window": { "timezone": "America/New_York", "start": "09:00", "end": "17:00", "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "variables": { "first_name": "Sara" }, "external_id": "reminder-20931" }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/scheduled-calls", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") request.Header.Set("Idempotency-Key", "reminder-20931") 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 // Schedule a call inside calling hours. It is placed at the first moment the window is open at or after dial_at. 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 { String body = """ { "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "dial_at": "2026-10-12T13:00:00Z", "call_window": { "timezone": "America/New_York", "start": "09:00", "end": "17:00", "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "variables": { "first_name": "Sara" }, "external_id": "reminder-20931" } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/scheduled-calls")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .header("Idempotency-Key", "reminder-20931") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Schedule a call inside calling hours. It is placed at the first moment the window is open at or after dial_at. 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.Post, "https://api.aigently.ai/v1/scheduled-calls") { Content = new StringContent( """ { "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "dial_at": "2026-10-12T13:00:00Z", "call_window": { "timezone": "America/New_York", "start": "09:00", "end": "17:00", "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "variables": { "first_name": "Sara" }, "external_id": "reminder-20931" } """, Encoding.UTF8, "application/json"), }; request.Headers.Add("Idempotency-Key", "reminder-20931"); 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", "Idempotency-Key: reminder-20931", ], CURLOPT_POSTFIELDS => json_encode([ "agent_id" => "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number" => "+12025550100", "dial_at" => "2026-10-12T13:00:00Z", "call_window" => [ "timezone" => "America/New_York", "start" => "09:00", "end" => "17:00", "days" => ["mon", "tue", "wed", "thu", "fri"], ], "variables" => [ "first_name" => "Sara", ], "external_id" => "reminder-20931", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` The body is the one a call takes, plus `dial_at`: the earliest the call may be placed, at most 30 days ahead. Leave it out, or send a time already past, and the call is placed now. With a `call_window`, it is placed at the first moment the window is open at or after `dial_at`, and the `dial_at` in the answer is already moved there. `Idempotency-Key` is required, as it is for a call. Everything a call can be refused for is checked when you schedule it, so a mistake is said at once, and checked again when it is placed, because an agent can be unpublished or a number listed as do-not-call in the meantime. If the window has closed by then, the call waits for its next opening. If every line is busy, or the organization has placed today's calls, it waits and tries again: a minute later for a busy line, an hour later for the day's limit. A [scheduled call](/reference/objects/ScheduledCall) is `scheduled` until its time comes, and then: | `status` | What happened | |---|---| | `placed` | It became a conversation. `conversation_id` names it, and it sends the usual events. | | `failed` | It was refused when its time came, and no call was made. `error_code` says why — see below. | | `cancelled` | You called it off. | `error_code` on a failed call is the code `POST /v1/calls` would have answered, like `agent_not_published` or `do_not_call`, or one of two more: `key_revoked` when the key that scheduled it no longer works, and `lines_busy` when it was put off 30 times because every line was busy or the day's calls were used up. List the calls still waiting: **curl** ```sh #!/bin/sh # List the calls still waiting curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/scheduled-calls?status=scheduled" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List the calls still waiting const response = await fetch("https://api.aigently.ai/v1/scheduled-calls?status=scheduled", { 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 # List the calls still waiting # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/scheduled-calls", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "status": "scheduled", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List the calls still waiting package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/scheduled-calls?status=scheduled", 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 // List the calls still waiting 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/scheduled-calls?status=scheduled")) .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 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 // List the calls still waiting 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/scheduled-calls?status=scheduled") { }; 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 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"; ``` Cancel one before its time: **curl** ```sh #!/bin/sh # Cancel a scheduled call. Only before its time: once placed, it is a conversation, which you end instead. curl -sS --fail-with-body -X DELETE "https://api.aigently.ai/v1/scheduled-calls/4b6d8f0a-2c4e-4a6c-9e8a-0c2e4a6c8e0b" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Cancel a scheduled call. Only before its time: once placed, it is a conversation, which you end instead. const response = await fetch("https://api.aigently.ai/v1/scheduled-calls/4b6d8f0a-2c4e-4a6c-9e8a-0c2e4a6c8e0b", { method: "DELETE", 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 # Cancel a scheduled call. Only before its time: once placed, it is a conversation, which you end instead. # pip install httpx import os import httpx response = httpx.delete( "https://api.aigently.ai/v1/scheduled-calls/4b6d8f0a-2c4e-4a6c-9e8a-0c2e4a6c8e0b", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Cancel a scheduled call. Only before its time: once placed, it is a conversation, which you end instead. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("DELETE", "https://api.aigently.ai/v1/scheduled-calls/4b6d8f0a-2c4e-4a6c-9e8a-0c2e4a6c8e0b", 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 // Cancel a scheduled call. Only before its time: once placed, it is a conversation, which you end instead. 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/scheduled-calls/4b6d8f0a-2c4e-4a6c-9e8a-0c2e4a6c8e0b")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("DELETE", 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 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 // Cancel a scheduled call. Only before its time: once placed, it is a conversation, which you end instead. 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.Delete, "https://api.aigently.ai/v1/scheduled-calls/4b6d8f0a-2c4e-4a6c-9e8a-0c2e4a6c8e0b") { }; 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 "DELETE", 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"; ``` Once its time has come it can no longer be cancelled. A call being placed right now answers `scheduled_call_placing`, and a call already placed is a conversation, which you [end](#end-it-yourself) instead. A test key's scheduled calls become test calls that ring nobody, and only test keys see them. A scheduled call is kept for 30 days after it is placed, cancelled or fails; the conversation it made is kept like any other. ## Calls refused before they start | Code | Why | |---|---| | `agent_not_outbound` | The agent answers calls; it does not place them. | | `agent_not_published` | Publish the agent first. | | `invalid_variables` | A value is missing or does not fit — `errors` names each. | | `destination_not_allowed` | A number this deployment does not call. | | `do_not_call` | The number is on your organization's [do-not-call list](#numbers-that-must-not-be-called). | | `caller_id_unavailable` | The agent has no number it may call from. | | `concurrency_limit_reached` | The organization already has as many calls going as it may. | | `daily_limit_reached` | The organization has placed today's calls. | | `test_number_required` | A test key calls only [test numbers](/guides/test-mode#test-numbers). | | `outside_call_window` | The call's [window](#calling-hours) is closed. `detail` says when it opens. | | `feature_disabled` | This deployment has phone calls switched off. A test key's calls are not affected. | ## Numbers that must not be called Your organization keeps one do-not-call list, and no agent rings a number on it: a call through the API, a campaign's contact, an appointment reminder, a transfer to a person or a test dial from the console is refused before anything is dialled, with `do_not_call`. Keep it from your own systems — when somebody opts out in your CRM, add them: **curl** ```sh #!/bin/sh # Add a number to the do-not-call list. With a live key: the list decides which real people are called. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/do-not-call" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "number": "+12025550188", "reason": "Asked not to be called again" }' ``` **JavaScript** ```js // Add a number to the do-not-call list. With a live key: the list decides which real people are called. const response = await fetch("https://api.aigently.ai/v1/do-not-call", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "number": "+12025550188", "reason": "Asked not to be called again" }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Add a number to the do-not-call list. With a live key: the list decides which real people are called. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/do-not-call", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "number": "+12025550188", "reason": "Asked not to be called again", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Add a number to the do-not-call list. With a live key: the list decides which real people are called. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "number": "+12025550188", "reason": "Asked not to be called again" }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/do-not-call", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Add a number to the do-not-call list. With a live key: the list decides which real people are called. 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 { String body = """ { "number": "+12025550188", "reason": "Asked not to be called again" } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/do-not-call")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Add a number to the do-not-call list. With a live key: the list decides which real people are called. 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.Post, "https://api.aigently.ai/v1/do-not-call") { Content = new StringContent( """ { "number": "+12025550188", "reason": "Asked not to be called again" } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "number" => "+12025550188", "reason" => "Asked not to be called again", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` This needs `do_not_call:write` and a live key: the list decides which real people are called, so a test key may read it but not change it. The list belongs to the whole organization, so reading or changing it also takes a key that reaches every project. Numbers are matched by their digits, so `+1 (202) 555-0100` and `12025550100` are one entry, and adding a listed number again answers `200` with the entry — taking the new `reason`, if you sent one. A number listed without its country code — `0798 798 906`, `(202) 555-0100` — also stops a call that dials it with one, and the other way round: the national forms are worked out from the number and from the line calling it. That can now and then refuse a number in another country that ends the same way. The refusal's `detail` names the entry, so you can check it. Ask whether a number is listed with `do_not_call:read`: **curl** ```sh #!/bin/sh # Ask whether a number may be called. An empty list means it is not on it. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/do-not-call?number=+12025550188" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Ask whether a number may be called. An empty list means it is not on it. const response = await fetch("https://api.aigently.ai/v1/do-not-call?number=+12025550188", { 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 # Ask whether a number may be called. An empty list means it is not on it. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/do-not-call", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "number": "+12025550188", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Ask whether a number may be called. An empty list means it is not on it. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/do-not-call?number=+12025550188", 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 // Ask whether a number may be called. An empty list means it is not on it. 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/do-not-call?number=+12025550188")) .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 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 // Ask whether a number may be called. An empty list means it is not on it. 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/do-not-call?number=+12025550188") { }; 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 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"; ``` Taking a number off lets it be called again, and is recorded in your organization's audit log under the key: **curl** ```sh #!/bin/sh # Take a number off the do-not-call list. With a live key. Recorded in the audit log under it. curl -sS --fail-with-body -X DELETE "https://api.aigently.ai/v1/do-not-call/+12025550188" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Take a number off the do-not-call list. With a live key. Recorded in the audit log under it. const response = await fetch("https://api.aigently.ai/v1/do-not-call/+12025550188", { method: "DELETE", 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 # Take a number off the do-not-call list. With a live key. Recorded in the audit log under it. # pip install httpx import os import httpx response = httpx.delete( "https://api.aigently.ai/v1/do-not-call/+12025550188", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Take a number off the do-not-call list. With a live key. Recorded in the audit log under it. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("DELETE", "https://api.aigently.ai/v1/do-not-call/+12025550188", 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 // Take a number off the do-not-call list. With a live key. Recorded in the audit log under it. 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/do-not-call/+12025550188")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("DELETE", 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 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 // Take a number off the do-not-call list. With a live key. Recorded in the audit log under it. 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.Delete, "https://api.aigently.ai/v1/do-not-call/+12025550188") { }; 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 "DELETE", 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"; ``` A test key's own calls never ring anybody, so the list does not apply to them. --- # Variables > How an agent's fields are declared, filled, checked, and kept from rewriting the agent. An agent's instructions and its first message can name values it is given when a conversation starts: `Hello {{first_name}}, I'm calling about your appointment on {{appointment_date}}.` Each name is a **variable**. A call, a chat, a campaign row and the widget all fill them the same way and are checked by the same rules. ## Which variables an agent has Writing `{{first_name}}` in the instructions or the first message *is* declaring it. Read an agent's variables from its `variables_schema`, a JSON Schema: **curl** ```sh #!/bin/sh # Read an agent and its variables curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read an agent and its variables const response = await fetch("https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", { 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 # Read an agent and its variables # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read an agent and its variables package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", 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 // Read an agent and its variables 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/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c")) .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 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 // Read an agent and its variables 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/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c") { }; 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 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"; ``` ```json { "version": "3f9c1e07", "type": "object", "properties": { "first_name": {"type": "string", "maxLength": 500, "title": "First name"}, "party_size": {"type": "integer", "minimum": 1, "maximum": 12, "default": 2, "title": "Party size"}, "visit_date": {"type": "string", "format": "date", "title": "Visit date"} }, "required": ["first_name", "visit_date"], "additionalProperties": true } ``` `version` changes when the variables change and at no other time, so you can tell an edit to the fields from any other edit to the agent. When it changes, your receivers are sent [`agent.updated`](/guides/webhooks#events-about-an-agent) with the new list. ## Pin a version An agent's fields change when somebody publishes. To keep an integration on the version it was built against, send `agent_version` when you start a call, a scheduled call, a chat or a browser call: the conversation is answered by that published version from its first turn to its last, and its values are checked against that version's fields, not today's. `GET /v1/agents/{id}/versions` lists every version the agent was published as, newest first, each with its own `variables_schema` and the note its publisher wrote. A version the agent never had is refused with `unknown_agent_version`. The conversation's `agent_version` says which one answered. ## Types | Type | Send | Notes | |---|---|---| | Text | `"Sara"` | Long text is shortened where it is put into the instructions. | | Number | `4` or `4.5` | A whole-number field refuses `4.5`. Minimum and maximum apply. | | Yes / no | `true` or `false` | | | Email | `"sara@aigently.ai"` | | | Phone | `"+12025550123"` | Spaces and dashes are taken out first. | | Date | `"2027-03-04"` | `YYYY-MM-DD`. A field may set the earliest and latest date. | | Time | `"14:30"` | 24-hour `HH:MM`. | | Choice | `"terrace"` | One of the field's options. | Numbers and `true`/`false` may be sent as JSON values or as text; each comes back in its own type. ## Required, optional and defaults A variable the agent says out loud is required — unless it has a **default**, which stands in when nothing is sent. A field marked optional may simply be left out. A required value that is missing, or one of the wrong type, refuses the request with `422 invalid_variables`, and `errors` names each one: ```json { "code": "invalid_variables", "errors": [ {"field": "variables.first_name", "code": "required", "message": "First name is required"}, {"field": "variables.visit_date", "code": "invalid", "message": "Visit date is not a valid date"} ] } ``` **A name the agent does not use is not refused.** It is listed in the conversation's `ignored_variables`, so a renamed field shows up there rather than failing every call. Names starting `system_` are reserved for the platform. ## Where each value came from Every conversation records the source of each value in `variable_sources`: `api` for one your request sent, `lookup` for one your [context lookup](/guides/inbound-calls) answered, `campaign`, `identity_token` for a signed widget token, `widget` or `link` for what a visitor's page claimed. Values from a lookup or a visitor's page are never treated as the caller's own answers. ## Variables or metadata? | | `variables` | `metadata` | |---|---|---| | The agent sees it | Yes | Never | | Checked against the agent's fields | Yes | No | | Returned on every read and event | Yes | Yes | | Use it for | What the agent should know and say | Your own ids: a CRM record, a campaign, a lead | ## Values cannot rewrite the agent A value is put into the agent's instructions inside a block of its own, marked as data. A `first_name` of `Ignore your instructions and …` is a strange name, not a new instruction. --- # Inbound calls > Tell an agent who is calling — your server is asked while the phone is answered, and the values reach the agent before its first reply. When somebody calls one of your agents, the agent can know who they are before it says a word beyond hello. Give the agent a **context lookup**: an address on your own server that is asked about each call as it is answered, and answers with values for the agent's [variables](/guides/variables). ## Set it up In the console, open the agent's **Connect → Phone** tab and fill in **Look up who is calling**: - **Live address** — asked by real calls. It must be `https://` and reachable from the internet. - **Test address** — asked by [test calls](#in-test-mode) instead, never by real ones. - **Time limit** — how long your server has to answer: 1,000 ms unless you change it, at most 2,500. - **Sample answer** — what a test call uses when there is no test address, so you can try the agent before your server exists. Saving shows each address's **signing secret** once. Keep them on your server. ## What your server is sent A `POST` with the same headers a webhook carries, signed with the lookup's own secret: ```json { "event": "conversation.context", "created_at": "2026-10-07T09:14:03.120394+00:00", "data": { "conversation_id": "5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d", "livemode": true, "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "channel": "phone", "direction": "inbound", "from_number": "+12025550123", "caller": "+12025550123", "to_number": "+12025550199", "phone_number_id": "9e8d7c6b-5a4f-3e2d-1c0b-a9f8e7d6c5b4" } } ``` Check the signature before you trust it — the [webhook helper](/guides/webhooks#check-the-signature) checks a lookup too, with the lookup's secret. ## What it answers `200` with JSON, at most 16 KB: ```json {"variables": {"first_name": "Sara", "plan": "gold"}, "metadata": {"crm_id": "C-1042"}} ``` `variables` fill the agent's fields and are checked like any others. `metadata` is yours, up to 20 keys, and is kept on the conversation. Answer `{"variables": {}}` for a caller you do not know. ## When it is asked, and who waits The lookup starts the moment the call is answered, and your server answers while the greeting plays — so an answer within the time limit costs the caller nothing. Only two things wait: - **A greeting that names a value**, like `Hello {{first_name}}`, waits for your answer — at most the time limit — so it can say it. The console's greeting editor says so when this is the case. - **A caller who talks before the greeting ends** waits, at most the time limit, for the values to arrive before the agent answers. The values are in the agent's instructions before its first reply either way. ## When it fails A slow or broken server never stops a call: the agent answers without the values. Nothing is retried — somebody is on the line. The conversation's `context` says what happened: | `context.status` | Means | |---|---| | `pending` | Your server is still being asked. | | `ok` | The values were used. | | `timeout` | No complete answer within the time limit. | | `bad_status` | Your server answered something other than `200`. | | `too_large` | The answer was over 16 KB. | | `invalid_answer` | The answer was not the JSON above, or a value did not fit — `problems` names each. | | `refused` | The address is not one the platform will send to. | | `failed` | The request could not be made. | | `busy` | Your organization had too many lookups waiting at once. | `context.ms` is how long the lookup took, and `applied_before_first_reply` whether the values were in time for the first reply. ## Fill fields from the phonebook For values that rarely change — a name, a plan, a member number — you need no server at all. Turn on **Fill fields from the phonebook** on the agent's **Connect → Phone** tab, and keep the project's phonebook in step with [the contacts API](/guides/contacts). When a call arrives, the entry with the caller's number fills the agent's fields before the call is answered, with the source `phonebook`. Only the agent's own fields are filled, and only with values that fit them. When the agent also has a lookup, the lookup's answer replaces what the phonebook said, since it is newer. ## Details a call brings with it A phone system that transfers callers to your agents can send what it already knows in `X-` headers on the call. Name each header and the field it fills on the trunk's **Settings** in the console — **Fields from SIP headers**, like `X-Customer-Id=customer_id` — and the agent that answers starts with those values, with the source `sip_header`. Only the headers you name are read, and a value that does not fit the field is left out rather than refusing the call. They are the call's own values: they replace what the phonebook says, and the lookup's answer does not replace them. ## A caller ID is not proof The number a call comes from is whatever the network was told, and anybody can set it. Use the lookup and the phonebook to *personalise* a call — the name, the plan, the last order — never to decide that the caller is who the number says. Values from either are never treated as the caller's own answers, and an agent that needs to know who it is talking to should ask, the way a person would. ## In test mode A test call to your agent asks its **test address**, or uses its sample answer, and never the live one. Make one from a test number with a test key: **curl** ```sh #!/bin/sh # Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/test/inbound-calls" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" }' ``` **JavaScript** ```js // Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. const response = await fetch("https://api.aigently.ai/v1/test/inbound-calls", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/test/inbound-calls", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/test/inbound-calls", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. 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 { String body = """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/test/inbound-calls")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. 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.Post, "https://api.aigently.ai/v1/test/inbound-calls") { Content = new StringContent( """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "agent_id" => "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number" => "+12025550100", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` The answer says what the lookup made of it — where the values came from, what was accepted and ignored, and the greeting they produced — and the call then plays out like any test call. With [`aigently listen`](/cli) and `--forward-lookups-to`, the lookup reaches your own machine. --- # Chat and streaming > Hold a conversation with an agent from your own app — one message at a time, as a whole reply or as it is written. The same agents your visitors talk to on your website can chat from your app, your back office or a channel we do not support yet. A chat needs the `chats:write` permission. ## Start a chat The first message starts it: **curl** ```sh #!/bin/sh # Start a chat curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/chats" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ -H "Idempotency-Key: chat-20931" \ --json '{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "message": "Hello, I would like to book a table.", "variables": { "first_name": "Sara" } }' ``` **JavaScript** ```js // Start a chat const response = await fetch("https://api.aigently.ai/v1/chats", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "chat-20931", }, body: JSON.stringify({ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "message": "Hello, I would like to book a table.", "variables": { "first_name": "Sara" } }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Start a chat # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/chats", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", "Idempotency-Key": "chat-20931", }, json={ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "message": "Hello, I would like to book a table.", "variables": { "first_name": "Sara", }, }, timeout=60, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Start a chat package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "message": "Hello, I would like to book a table.", "variables": { "first_name": "Sara" } }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/chats", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") request.Header.Set("Idempotency-Key", "chat-20931") 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 // Start a chat 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 { String body = """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "message": "Hello, I would like to book a table.", "variables": { "first_name": "Sara" } } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/chats")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .header("Idempotency-Key", "chat-20931") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Start a chat 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.Post, "https://api.aigently.ai/v1/chats") { Content = new StringContent( """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "message": "Hello, I would like to book a table.", "variables": { "first_name": "Sara" } } """, Encoding.UTF8, "application/json"), }; request.Headers.Add("Idempotency-Key", "chat-20931"); 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", "Idempotency-Key: chat-20931", ], CURLOPT_POSTFIELDS => json_encode([ "agent_id" => "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "message" => "Hello, I would like to book a table.", "variables" => [ "first_name" => "Sara", ], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` The answer is a `chat.turn`: the agent's greeting in `opening` (first turn only — show it above the reply), its `reply`, and the `conversation_id` to send the next message to. `variables` are read only when a chat starts, so nothing said later can change what the agent was told about the person. An `Idempotency-Key` is optional here: the same request with the same key returns the same chat. ## Send the next message **curl** ```sh #!/bin/sh # Send the next message curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "message": "For four people, at seven." }' ``` **JavaScript** ```js // Send the next message const response = await fetch("https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "message": "For four people, at seven." }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Send the next message # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "message": "For four people, at seven.", }, timeout=60, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Send the next message package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "message": "For four people, at seven." }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Send the next message 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 { String body = """ { "message": "For four people, at seven." } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Send the next message 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.Post, "https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages") { Content = new StringContent( """ { "message": "For four people, at seven." } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "message" => "For four people, at seven.", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` The agent keeps the history; you keep the id. There is nothing else to keep in step — no turn to count, no transcript to send. **One message at a time.** A message sent while the agent is still answering the previous one is refused with `409 conversation_busy`: wait for the reply. A message sent again with the same `Idempotency-Key` returns the same reply without asking the agent twice — streamed, if the retry asks for a stream. If the first attempt's reply failed, the retry gets that failure again (`502 upstream_unavailable`); send the message under a new key to ask once more. A chat follows its agent: once the agent is unpublished, archived or deleted, the chat takes no more messages (`409 agent_not_published`), and each message is answered by the agent's published version, never by edits that have not been published. ## Stream the reply Send `stream: true` — or `Accept: text/event-stream` — and the reply arrives as it is written, as server-sent events: **curl** ```sh #!/bin/sh # Stream the reply as it is written curl -sS --fail-with-body -N -X POST "https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "message": "Can I bring my dog?", "stream": true }' ``` **JavaScript** ```js // Stream the reply as it is written const response = await fetch("https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "message": "Can I bring my dog?", "stream": true }), }); if (!response.ok) { const problem = await response.json(); throw new Error(`${problem.code}: ${problem.detail}`); } // Each event is an "event:" line, a "data:" line of JSON, and a blank line. const decoder = new TextDecoder(); let buffer = ""; for await (const chunk of response.body) { buffer += decoder.decode(chunk, { stream: true }); let end; while ((end = buffer.indexOf("\n\n")) >= 0) { const [eventLine, dataLine] = buffer.slice(0, end).split("\n"); buffer = buffer.slice(end + 2); const event = eventLine.slice("event: ".length); const data = JSON.parse(dataLine.slice("data: ".length)); if (event === "delta") process.stdout.write(data.text); if (event === "done") console.log("\n", data); if (event === "error") throw new Error(`${data.code}: ${data.detail}`); } } ``` **Python** ```python # Stream the reply as it is written # pip install httpx import json import os import httpx with httpx.stream( "POST", "https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "message": "Can I bring my dog?", "stream": True, }, timeout=60, ) as response: if response.is_error: raise SystemExit(response.read().decode()) # Each event is an "event:" line, a "data:" line of JSON, and a blank line. event = None for line in response.iter_lines(): if line.startswith("event: "): event = line.removeprefix("event: ") elif line.startswith("data: "): data = json.loads(line.removeprefix("data: ")) if event == "delta": print(data["text"], end="", flush=True) elif event == "done": print("\n", data) elif event == "error": raise SystemExit(f"{data['code']}: {data['detail']}") ``` **Go** ```go // Stream the reply as it is written package main import ( "bufio" "bytes" "encoding/json" "fmt" "io" "net/http" "os" "strings" ) func main() { payload := []byte(`{ "message": "Can I bring my dog?", "stream": true }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") response, err := http.DefaultClient.Do(request) if err != nil { panic(err) } defer response.Body.Close() if response.StatusCode >= 400 { body, _ := io.ReadAll(response.Body) fmt.Fprintln(os.Stderr, string(body)) os.Exit(1) } // Each event is an "event:" line, a "data:" line of JSON, and a blank line. scanner := bufio.NewScanner(response.Body) scanner.Buffer(make([]byte, 64*1024), 1024*1024) event := "" for scanner.Scan() { line := scanner.Text() if name, found := strings.CutPrefix(line, "event: "); found { event = name continue } data, found := strings.CutPrefix(line, "data: ") if !found { continue } switch event { case "delta": var delta struct { Text string `json:"text"` } json.Unmarshal([]byte(data), &delta) fmt.Print(delta.Text) case "done": fmt.Println("\n" + data) case "error": fmt.Fprintln(os.Stderr, data) os.Exit(1) } } } ``` **Java** ```java // Stream the reply as it is written import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.stream.Stream; public class Main { public static void main(String[] args) throws Exception { String body = """ { "message": "Can I bring my dog?", "stream": true } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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> response = client.send(request, HttpResponse.BodyHandlers.ofLines()); if (response.statusCode() >= 400) { response.body().forEach(System.err::println); System.exit(1); } // Each event is an "event:" line, a "data:" line of JSON, and a blank line. // Read each data line with your JSON library. response.body().filter(line -> !line.isEmpty()).forEach(System.out::println); } } ``` **C#** ```csharp // Stream the reply as it is written using System.Net.Http.Headers; using System.Text; using System.Text.Json; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("AIGENTLY_API_KEY")); var request = new HttpRequestMessage(HttpMethod.Post, "https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages") { Content = new StringContent( """ { "message": "Can I bring my dog?", "stream": true } """, Encoding.UTF8, "application/json"), }; using var response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead); if (!response.IsSuccessStatusCode) { Console.Error.WriteLine(await response.Content.ReadAsStringAsync()); return 1; } // Each event is an "event:" line, a "data:" line of JSON, and a blank line. using var reader = new StreamReader(await response.Content.ReadAsStreamAsync()); var eventName = ""; while (await reader.ReadLineAsync() is { } line) { if (line.StartsWith("event: ")) { eventName = line["event: ".Length..]; continue; } if (!line.StartsWith("data: ")) { continue; } var data = line["data: ".Length..]; if (eventName == "delta") { Console.Write(JsonDocument.Parse(data).RootElement.GetProperty("text").GetString()); } else if (eventName == "done") { Console.WriteLine("\n" + data); } else if (eventName == "error") { Console.Error.WriteLine(data); return 1; } } return 0; ``` **PHP** ```php true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "message" => "Can I bring my dog?", "stream" => true, ]), // Each event is an "event:" line, a "data:" line of JSON, and a blank line. CURLOPT_WRITEFUNCTION => function ($curl, $chunk) use (&$event, &$buffer, &$failed) { $buffer .= $chunk; while (($end = strpos($buffer, "\n")) !== false) { $line = substr($buffer, 0, $end); $buffer = substr($buffer, $end + 1); if (str_starts_with($line, "event: ")) { $event = substr($line, 7); } elseif (str_starts_with($line, "data: ")) { $data = substr($line, 6); if ($event === "delta") { echo json_decode($data, true)["text"]; } elseif ($event === "done") { echo "\n", $data, "\n"; } elseif ($event === "error") { fwrite(STDERR, $data . "\n"); $failed = true; } } } return strlen($chunk); }, ]); curl_exec($curl); if ($failed || curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $buffer . "\n"); exit(1); } ``` | Event | `data` | |---|---| | `delta` | `{"text": "…"}` — the next words of the reply. | | `status` | `{"text": "…"}` — the agent started using one of its tools, in words for a person. | | `done` | The whole `chat.turn`, exactly as the answer without streaming. | | `error` | A [problem document](/errors) — the headers are long gone, so this is how a stream fails. | **Read `done` rather than gluing the deltas together.** It carries the conversation id, what was collected and whether the agent has finished, which the deltas do not. ## Send a picture Where the agent accepts images, upload one first, then name it in the next message's `attachment_ids` — up to four a message: **curl** ```sh #!/bin/sh # Upload a picture to send. Send the id it returns in a message's attachment_ids. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/attachments" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ -F "agent_id=3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f" \ -F "file=@photo.jpg;type=image/jpeg" ``` **JavaScript** ```js import { readFile } from "node:fs/promises"; // Upload a picture to send. Send the id it returns in a message's attachment_ids. const form = new FormData(); form.append("agent_id", "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f"); form.append("file", new Blob([await readFile("photo.jpg")], { type: "image/jpeg" }), "photo.jpg"); const response = await fetch("https://api.aigently.ai/v1/attachments", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, }, body: form, }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Upload a picture to send. Send the id it returns in a message's attachment_ids. # pip install httpx import os import httpx with open("photo.jpg", "rb") as upload: response = httpx.post( "https://api.aigently.ai/v1/attachments", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, data={ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", }, files={"file": ("photo.jpg", upload, "image/jpeg")}, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Upload a picture to send. Send the id it returns in a message's attachment_ids. package main import ( "bytes" "fmt" "io" "mime/multipart" "net/http" "os" ) func main() { var form bytes.Buffer writer := multipart.NewWriter(&form) writer.WriteField("agent_id", "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f") part, _ := writer.CreateFormFile("file", "photo.jpg") contents, err := os.ReadFile("photo.jpg") if err != nil { panic(err) } part.Write(contents) writer.Close() request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/attachments", &form) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", writer.FormDataContentType()) 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 // Upload a picture to send. Send the id it returns in a message's attachment_ids. import java.io.ByteArrayOutputStream; import java.nio.file.Files; import java.nio.file.Path; 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 { String boundary = Long.toHexString(System.nanoTime()); ByteArrayOutputStream form = new ByteArrayOutputStream(); form.write(("--" + boundary + "\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\n3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f\r\n--" + boundary + "\r\nContent-Disposition: form-data; name=\"file\"; filename=\"photo.jpg\"\r\n" + "Content-Type: image/jpeg\r\n\r\n").getBytes()); form.write(Files.readAllBytes(Path.of("photo.jpg"))); form.write(("\r\n--" + boundary + "--\r\n").getBytes()); HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/attachments")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "multipart/form-data; boundary=" + boundary) .method("POST", HttpRequest.BodyPublishers.ofByteArray(form.toByteArray())) .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 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 // Upload a picture to send. Send the id it returns in a message's attachment_ids. using System.Net.Http.Headers; using System.Text; var form = new MultipartFormDataContent(); form.Add(new StringContent("3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f"), "agent_id"); var upload = new ByteArrayContent(File.ReadAllBytes("photo.jpg")); upload.Headers.ContentType = new MediaTypeHeaderValue("image/jpeg"); form.Add(upload, "file", "photo.jpg"); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("AIGENTLY_API_KEY")); var request = new HttpRequestMessage(HttpMethod.Post, "https://api.aigently.ai/v1/attachments") { Content = form, }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => [ "agent_id" => "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "file" => new CURLFile("photo.jpg", "image/jpeg"), ], ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` A picture nobody sends is deleted after six hours. ## End it **curl** ```sh #!/bin/sh # End a call or a chat curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/end" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // End a call or a chat const response = await fetch("https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/end", { method: "POST", 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 # End a call or a chat # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/end", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // End a call or a chat package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/end", 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 // End a call or a chat 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/end")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("POST", 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 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 // End a call or a chat 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.Post, "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/end") { }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => "", ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` A chat also ends on its own after a while without messages. A message to an ended chat is refused with `409 conversation_ended`; start a new one. ## Limits | Limit | | |---|---| | A message | 4,000 characters. | | Messages in one conversation | 20 a minute, and a ceiling on the whole conversation — `conversation_limit_reached` past it. | | Messages per key | 1,200 a minute. | Chats are charged like chats in the console, from the organization's credit — chats made with a test key too, because they use the agent's real model. When the credit runs out, a message is refused with `402 insufficient_credit`. --- # Reading and syncing conversations > List, search and read conversations, their transcripts and recordings, keep your own copy up to date, and delete them. Every call and chat is a **conversation**, read the same way whichever door it came through: the console, the widget, a phone line, a campaign or this API. Reading needs `conversations:read`; a transcript also needs `transcripts:read`, and a recording `recordings:read`. ## List them **curl** ```sh #!/bin/sh # List conversations curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations?agent_id=8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c&status=completed&limit=10" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List conversations const response = await fetch("https://api.aigently.ai/v1/conversations?agent_id=8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c&status=completed&limit=10", { 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 # List conversations # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "status": "completed", "limit": 10, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List conversations package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations?agent_id=8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c&status=completed&limit=10", 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 // List conversations 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/conversations?agent_id=8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c&status=completed&limit=10")) .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 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 // List conversations 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/conversations?agent_id=8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c&status=completed&limit=10") { }; 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 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"; ``` Newest first, 20 a page unless you ask for up to 100. Filter by agent, project, channel, direction, status (repeat it for several), disposition, the analysis's outcome, who ended it, mode, numbers, campaign, your own `external_id`, and when it started or changed. Each page has `has_more` and a `next_cursor`: send it back as `cursor`, with the same filters, for the next page. A cursor works only for the key, the mode and the filters that made it. ## Find one by what was said **curl** ```sh #!/bin/sh # Find conversations by what was said. Each one comes with the passage that matched. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations?q=refund&limit=10" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Find conversations by what was said. Each one comes with the passage that matched. const response = await fetch("https://api.aigently.ai/v1/conversations?q=refund&limit=10", { 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 # Find conversations by what was said. Each one comes with the passage that matched. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "q": "refund", "limit": 10, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Find conversations by what was said. Each one comes with the passage that matched. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations?q=refund&limit=10", 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 // Find conversations by what was said. Each one comes with the passage that matched. 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/conversations?q=refund&limit=10")) .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 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 // Find conversations by what was said. Each one comes with the passage that matched. 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/conversations?q=refund&limit=10") { }; 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 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"; ``` `q` searches the transcripts, the same search as the console's, and needs `transcripts:read` as well. A word also finds longer words that start with it, so `refund` finds `refunded`. Put a phrase in quotes to find it as written, and write `-word` to leave out conversations that have the word. Every other filter still applies. Each result carries `match`: the passage that matched, as plain text. A key may search 30 times a minute. A conversation can be found about a minute after it ends. ## Read one **curl** ```sh #!/bin/sh # Read a conversation with its transcript curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read a conversation with its transcript const response = await fetch("https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript", { 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 # Read a conversation with its transcript # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "include": "transcript", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read a conversation with its transcript package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript", 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 // Read a conversation with its transcript 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript")) .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 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 // Read a conversation with its transcript 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript") { }; 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 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"; ``` The [conversation](/reference/objects/Conversation) carries its status and how it ended, its numbers, the values it started with and where each came from, your metadata, the lookup's result, the answers collected, the analysis, the recording's state and its times. `include=transcript` adds what was said. The transcript alone: **curl** ```sh #!/bin/sh # Read a transcript curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/transcript" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read a transcript const response = await fetch("https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/transcript", { 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 # Read a transcript # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/transcript", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read a transcript package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/transcript", 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 // Read a transcript 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/transcript")) .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 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 // Read a transcript 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/transcript") { }; 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 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"; ``` Entries are in order: `user` is the person, `assistant` the agent, `tool` a tool the agent used, and `note` something the platform recorded, like a handover. ## The recording A link to the audio works for **five minutes**, so download it straight away rather than storing the link: **curl** ```sh #!/bin/sh # Get a link to a recording. The link works for five minutes, so download the audio straight away. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Get a link to a recording. The link works for five minutes, so download the audio straight away. const response = await fetch("https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording", { 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 # Get a link to a recording. The link works for five minutes, so download the audio straight away. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Get a link to a recording. The link works for five minutes, so download the audio straight away. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording", 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 // Get a link to a recording. The link works for five minutes, so download the audio straight away. 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording")) .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 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 // Get a link to a recording. The link works for five minutes, so download the audio straight away. 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording") { }; 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 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"; ``` The file is stereo Ogg: the caller on the left, the agent on the right. Each key may ask for 60 links a minute and 2,000 a day, and every link is recorded in your organization's audit log. ## What it cost Ask for `include=cost`, which needs `billing:read` as well: **curl** ```sh #!/bin/sh # Read what a conversation cost curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=cost" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read what a conversation cost const response = await fetch("https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=cost", { 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 # Read what a conversation cost # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "include": "cost", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read what a conversation cost package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=cost", 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 // Read what a conversation cost 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=cost")) .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 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 // Read what a conversation cost 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=cost") { }; 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 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"; ``` `cost.credits` is what the conversation cost: its own charge and every analysis of it, less any refund. A chat is charged as it goes, so an open chat's cost can still grow. Every charge behind the number is in the [credit history](/guides/billing). ## Run the analysis again Run the agent's analysis on a conversation that has ended: again, after you change the agent's analysis settings, or for the first time on one that was never analysed. This needs `analysis:run`: **curl** ```sh #!/bin/sh # Analyse a conversation again. It costs credit, like any analysis. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/analysis" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Analyse a conversation again. It costs credit, like any analysis. const response = await fetch("https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/analysis", { method: "POST", 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 # Analyse a conversation again. It costs credit, like any analysis. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/analysis", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Analyse a conversation again. It costs credit, like any analysis. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/analysis", 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 // Analyse a conversation again. It costs credit, like any analysis. 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/analysis")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("POST", 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 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 // Analyse a conversation again. It costs credit, like any analysis. 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.Post, "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/analysis") { }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => "", ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` The answer is the conversation with its new `analysis`, and `conversation.analyzed` is sent again. Each run costs credit, like the first one, and an organization may run 10 a minute. A conversation still in progress is refused with `409 conversation_in_progress`, and one where too little was said with `422 conversation_too_short`. ## Keep your copy in sync Ask for what changed instead of reading everything again: **curl** ```sh #!/bin/sh # Sync what changed. Send each page's next_cursor back as cursor= until has_more is false. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations?order=changed&changed_after=2026-10-01T00:00:00Z" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Sync what changed. Send each page's next_cursor back as cursor= until has_more is false. const response = await fetch("https://api.aigently.ai/v1/conversations?order=changed&changed_after=2026-10-01T00:00:00Z", { 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 # Sync what changed. Send each page's next_cursor back as cursor= until has_more is false. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "order": "changed", "changed_after": "2026-10-01T00:00:00Z", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Sync what changed. Send each page's next_cursor back as cursor= until has_more is false. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations?order=changed&changed_after=2026-10-01T00:00:00Z", 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 // Sync what changed. Send each page's next_cursor back as cursor= until has_more is false. 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/conversations?order=changed&changed_after=2026-10-01T00:00:00Z")) .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 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 // Sync what changed. Send each page's next_cursor back as cursor= until has_more is false. 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/conversations?order=changed&changed_after=2026-10-01T00:00:00Z") { }; 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 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"; ``` With `order=changed`, the oldest change comes first. Read until `has_more` is `false`, keep the last page's `next_cursor`, and next time start from it: you get every conversation that changed since, once, in order. Changes from the last minute wait for a later page, so a conversation still being written is never skipped. Every conversation has a `revision` that only goes up: of two copies, keep the higher. ## Delete one Deleting needs `conversations:delete`, a permission no starting point in the console includes: **curl** ```sh #!/bin/sh # Delete a conversation. With its recording, for good. curl -sS --fail-with-body -X DELETE "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Delete a conversation. With its recording, for good. const response = await fetch("https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d", { method: "DELETE", 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 # Delete a conversation. With its recording, for good. # pip install httpx import os import httpx response = httpx.delete( "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Delete a conversation. With its recording, for good. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("DELETE", "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d", 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 // Delete a conversation. With its recording, for good. 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("DELETE", 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 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 // Delete a conversation. With its recording, for good. 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.Delete, "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d") { }; 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 "DELETE", 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"; ``` The transcript, the recording and any pictures go with it, for good. A call still in progress is refused with `409 conversation_in_progress`: end it first. A chat that is still open is charged for what it used, then deleted. What it cost stays in the credit history. It is listed below with the reason `api`, `conversation.deleted` is sent to your receivers, and the organization's audit log records which key deleted it. ## Deleted conversations A conversation can be deleted — by the organization's retention, from the console, through this API, or with its agent or project. Ask for those too, and remove them from your copy: **curl** ```sh #!/bin/sh # List deleted conversations curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/deleted" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List deleted conversations const response = await fetch("https://api.aigently.ai/v1/conversations/deleted", { 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 # List deleted conversations # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations/deleted", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List deleted conversations package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations/deleted", 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 // List deleted conversations 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/conversations/deleted")) .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 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 // List deleted conversations 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/conversations/deleted") { }; 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 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"; ``` Deletions are listed for 30 days. ## What a test key sees A test key reads, searches and deletes only conversations made with test keys, and a live key never sees them. A real conversation asked for with a test key is `404`, as if it did not exist. Running the analysis again on a test call gives its sample analysis again, at no cost; a test chat is analysed by the agent's real model, and charged. --- # Webhooks > Hear about every conversation as it happens, signed so you know it came from Aigently. A webhook receiver is an address on your server that the platform POSTs events to. Add one in the console under **Webhooks**, choose its events, and keep its signing secret, which is shown once. ## Events about a conversation | Event | When | |---|---| | `conversation.started` | A call was answered, a browser caller joined, or a chat's first message arrived. | | `conversation.ended` | Once, the first time a conversation ends — answered or not. | | `conversation.updated` | Something changed after the end — an outcome corrected, for one. | | `conversation.analyzed` | The analysis finished: outcome, sentiment, the checks it scored. | | `conversation.recording_ready` | The recording is stored. It carries no link: [ask for one](/guides/conversations#the-recording) when you need it. | | `conversation.deleted` | Removed by retention, from the console, [through the API](/guides/conversations#delete-one), or with its agent or project. | | `conversation.transcript` | The whole transcript. It carries what was said, so it is off until you choose it. | ## Events about an agent `agent.updated` is sent when an agent's fields change: the [variables](/guides/variables) a conversation can start with, the answers it collects, or what its analysis writes. An edit to a published agent takes effect from the next conversation, so an edit that adds a required variable is one your integration needs to hear about before its next call. It carries the agent as [Get an agent](/reference/getAgent) describes it, with the three lists, `analysis_enabled`, and `changed`, which names the lists that changed. Each list has a `version`: keep it, and you can tell a change to the fields from any other edit. An edit that changes no field — a new name, reworded instructions with the same placeholders — sends nothing. It goes to live receivers only: an agent's fields are not test data. A receiver made before the event existed hears it once `agent.updated` is added to its `events`. ## Events about a campaign A [campaign](/guides/campaigns) sends `campaign.started`, `campaign.paused`, `campaign.completed` and `campaign.cancelled` as it moves — whether you moved it, somebody did in the console, or it paused itself — and `campaign.contact_finished` with one person's final result. They go to live receivers only. There are more — forms, workflow steps, appointments, handovers — listed beside each receiver in the console. Every event of the last 30 days is also in the [event feed](/guides/events), whether or not a receiver heard it. Which events a call sends as it ends is in the [endings table](/guides/outbound-calls#how-a-call-ends). ## What you receive ```json { "id": "0f9a7c2e-5b1d-4e8a-9c3f-2d6b8e1a4c7f", "event": "conversation.ended", "created_at": "2026-10-07T09:14:03.120394+00:00", "livemode": true, "revision": 6, "data": { "object": "conversation", "id": "5f0c9a52-…", "status": "completed", "…": "…" } } ``` `data` is the [conversation](/reference/objects/Conversation), as the API reads it. `id` is the event's own id: the same event delivered twice has the same `id`, so keep the ones you have seen. Events can arrive out of order — keep the copy with the higher `revision`. Answer `2xx` quickly and do the work afterwards; anything else is retried with growing waits. ## Check the signature Every delivery is signed with your receiver's secret, the [Standard Webhooks](https://www.standardwebhooks.com/) way — so any of that standard's libraries checks it — in three headers: `webhook-id`, `webhook-timestamp` and `webhook-signature`. Check it against the body **exactly as it arrived**, before parsing it, and refuse anything older than five minutes. This function does all of it, in your language: **curl** ```sh #!/bin/sh # Check a saved delivery's signature by hand, with openssl: the body on standard input, the three # headers in WEBHOOK_ID, WEBHOOK_TIMESTAMP and WEBHOOK_SIGNATURE. A server should use one of the # other languages, which compare in constant time. set -eu body="$(mktemp)" trap 'rm -f "$body"' EXIT cat > "$body" now="$(date +%s)" age=$((now - WEBHOOK_TIMESTAMP)) if [ "${age#-}" -gt 300 ]; then echo "timestamp outside the tolerance" >&2 exit 1 fi key="$(printf '%s' "${AIGENTLY_WEBHOOK_SECRET#whsec_}" | base64 -d | od -An -v -tx1 | tr -d ' \n')" expected="$({ printf '%s.%s.' "$WEBHOOK_ID" "$WEBHOOK_TIMESTAMP"; cat "$body"; } \ | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$key" -binary | base64)" for entry in $WEBHOOK_SIGNATURE; do if [ "$entry" = "v1,$expected" ]; then echo "verified" exit 0 fi done echo "signature does not match" >&2 exit 1 ``` **JavaScript** ```js // Check a webhook's signature, then read its event. // The same function checks a context lookup request, with the lookup's secret. import { createHmac, timingSafeEqual } from "node:crypto"; import { text } from "node:stream/consumers"; const TOLERANCE_SECONDS = 5 * 60; // `body` is the request body exactly as it arrived: parse it only after this has checked it. // `headers` has lowercase names, as Node gives them. export function unwrap(body, headers, secret) { const id = headers["webhook-id"]; const timestamp = headers["webhook-timestamp"]; const signatures = headers["webhook-signature"]; if (!id || !timestamp || !signatures) throw new Error("missing webhook headers"); if (!(Math.abs(Date.now() / 1000 - Number(timestamp)) <= TOLERANCE_SECONDS)) { throw new Error("timestamp outside the tolerance"); } const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64"); const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest(); const matched = signatures.split(" ").some((entry) => { const [version, signature] = entry.split(","); if (version !== "v1" || !signature) return false; const offered = Buffer.from(signature, "base64"); return offered.length === expected.length && timingSafeEqual(offered, expected); }); if (!matched) throw new Error("signature does not match"); return JSON.parse(body); } // Try it with a delivery: the body on standard input, the three headers in the environment. const event = unwrap( await text(process.stdin), { "webhook-id": process.env.WEBHOOK_ID, "webhook-timestamp": process.env.WEBHOOK_TIMESTAMP, "webhook-signature": process.env.WEBHOOK_SIGNATURE, }, process.env.AIGENTLY_WEBHOOK_SECRET, ); console.log(`verified ${event.event} ${event.id}`); ``` **Python** ```python # Check a webhook's signature, then read its event. # The same function checks a context lookup request, with the lookup's secret. import base64 import hashlib import hmac import json import os import sys import time TOLERANCE_SECONDS = 5 * 60 def unwrap(body: bytes, headers, secret: str) -> dict: """The event, once its signature is checked. Raises ValueError otherwise. `body` is the request body exactly as it arrived: parse it only after this has checked it. `headers` is any mapping of the request's headers; most frameworks read theirs in any case. """ message_id = headers.get("webhook-id") timestamp = headers.get("webhook-timestamp") signatures = headers.get("webhook-signature") if not message_id or not timestamp or not signatures: raise ValueError("missing webhook headers") if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS: raise ValueError("timestamp outside the tolerance") key = base64.b64decode(secret.removeprefix("whsec_")) signed = f"{message_id}.{timestamp}.".encode() + body expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode() for entry in signatures.split(" "): version, _, signature = entry.partition(",") if version == "v1" and hmac.compare_digest(signature, expected): return json.loads(body) raise ValueError("signature does not match") if __name__ == "__main__": # Try it with a delivery: the body on standard input, the three headers in the environment. event = unwrap( sys.stdin.buffer.read(), { "webhook-id": os.environ["WEBHOOK_ID"], "webhook-timestamp": os.environ["WEBHOOK_TIMESTAMP"], "webhook-signature": os.environ["WEBHOOK_SIGNATURE"], }, os.environ["AIGENTLY_WEBHOOK_SECRET"], ) print("verified", event["event"], event["id"]) ``` **Go** ```go // Check a webhook's signature, then read its event. // The same function checks a context lookup request, with the lookup's secret. package main import ( "crypto/hmac" "crypto/sha256" "encoding/base64" "encoding/json" "errors" "fmt" "io" "net/http" "os" "strconv" "strings" "time" ) const toleranceSeconds = 5 * 60 // Unwrap checks the signature on a webhook and returns its event. body is the request body exactly // as it arrived: parse it only after this has checked it. func Unwrap(body []byte, headers http.Header, secret string) (map[string]any, error) { id := headers.Get("webhook-id") timestamp := headers.Get("webhook-timestamp") signatures := headers.Get("webhook-signature") if id == "" || timestamp == "" || signatures == "" { return nil, errors.New("missing webhook headers") } sent, err := strconv.ParseInt(timestamp, 10, 64) if err != nil || time.Since(time.Unix(sent, 0)).Abs() > toleranceSeconds*time.Second { return nil, errors.New("timestamp outside the tolerance") } key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_")) if err != nil { return nil, errors.New("not a webhook signing secret") } mac := hmac.New(sha256.New, key) mac.Write([]byte(id + "." + timestamp + ".")) mac.Write(body) expected := mac.Sum(nil) for _, entry := range strings.Split(signatures, " ") { version, signature, _ := strings.Cut(entry, ",") offered, err := base64.StdEncoding.DecodeString(signature) if version == "v1" && err == nil && hmac.Equal(offered, expected) { var event map[string]any if err := json.Unmarshal(body, &event); err != nil { return nil, err } return event, nil } } return nil, errors.New("signature does not match") } func main() { // Try it with a delivery: the body on standard input, the three headers in the environment. body, _ := io.ReadAll(os.Stdin) headers := http.Header{} headers.Set("webhook-id", os.Getenv("WEBHOOK_ID")) headers.Set("webhook-timestamp", os.Getenv("WEBHOOK_TIMESTAMP")) headers.Set("webhook-signature", os.Getenv("WEBHOOK_SIGNATURE")) event, err := Unwrap(body, headers, os.Getenv("AIGENTLY_WEBHOOK_SECRET")) if err != nil { fmt.Fprintln(os.Stderr, err) os.Exit(1) } fmt.Println("verified", event["event"], event["id"]) } ``` **Java** ```java // Check a webhook's signature. Once it passes, read the event with your JSON library. // The same method checks a context lookup request, with the lookup's secret. import java.nio.charset.StandardCharsets; import java.security.MessageDigest; import java.util.Base64; import java.util.Map; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; public class Main { static final long TOLERANCE_SECONDS = 5 * 60; /** * The body, once its signature is checked; throws otherwise. `body` is the request body exactly * as it arrived, and `headers` has lowercase names. */ static String unwrap(byte[] body, Map headers, String secret) throws Exception { String id = headers.get("webhook-id"); String timestamp = headers.get("webhook-timestamp"); String signatures = headers.get("webhook-signature"); if (id == null || timestamp == null || signatures == null) { throw new SecurityException("missing webhook headers"); } long now = System.currentTimeMillis() / 1000; if (!timestamp.matches("\\d{1,12}") || Math.abs(now - Long.parseLong(timestamp)) > TOLERANCE_SECONDS) { throw new SecurityException("timestamp outside the tolerance"); } byte[] key = Base64.getDecoder().decode(secret.replaceFirst("^whsec_", "")); Mac mac = Mac.getInstance("HmacSHA256"); mac.init(new SecretKeySpec(key, "HmacSHA256")); mac.update((id + "." + timestamp + ".").getBytes(StandardCharsets.UTF_8)); byte[] expected = mac.doFinal(body); for (String entry : signatures.split(" ")) { String[] parts = entry.split(",", 2); if (parts.length != 2 || !parts[0].equals("v1")) { continue; } byte[] offered; try { offered = Base64.getDecoder().decode(parts[1]); } catch (IllegalArgumentException malformed) { continue; } if (MessageDigest.isEqual(offered, expected)) { return new String(body, StandardCharsets.UTF_8); } } throw new SecurityException("signature does not match"); } public static void main(String[] args) throws Exception { // Try it with a delivery: the body on standard input, the three headers in the environment. String event = unwrap( System.in.readAllBytes(), Map.of( "webhook-id", System.getenv("WEBHOOK_ID"), "webhook-timestamp", System.getenv("WEBHOOK_TIMESTAMP"), "webhook-signature", System.getenv("WEBHOOK_SIGNATURE")), System.getenv("AIGENTLY_WEBHOOK_SECRET")); System.out.println("verified " + event); } } ``` **C#** ```csharp // Check a webhook's signature, then read its event. // The same function checks a context lookup request, with the lookup's secret. using System.Security.Cryptography; using System.Text; using System.Text.Json; // Try it with a delivery: the body on standard input, the three headers in the environment. using var input = new MemoryStream(); Console.OpenStandardInput().CopyTo(input); using var webhookEvent = Webhooks.Unwrap( input.ToArray(), new Dictionary { ["webhook-id"] = Environment.GetEnvironmentVariable("WEBHOOK_ID"), ["webhook-timestamp"] = Environment.GetEnvironmentVariable("WEBHOOK_TIMESTAMP"), ["webhook-signature"] = Environment.GetEnvironmentVariable("WEBHOOK_SIGNATURE"), }, Environment.GetEnvironmentVariable("AIGENTLY_WEBHOOK_SECRET") ?? ""); var root = webhookEvent.RootElement; Console.WriteLine($"verified {root.GetProperty("event")} {root.GetProperty("id")}"); static class Webhooks { const long ToleranceSeconds = 5 * 60; // The event, once its signature is checked; throws otherwise. `body` is the request body // exactly as it arrived: parse it only after this has checked it. public static JsonDocument Unwrap( byte[] body, IReadOnlyDictionary headers, string secret) { if (headers.GetValueOrDefault("webhook-id") is not { Length: > 0 } id || headers.GetValueOrDefault("webhook-timestamp") is not { Length: > 0 } timestamp || headers.GetValueOrDefault("webhook-signature") is not { Length: > 0 } signatures) { throw new CryptographicException("missing webhook headers"); } if (!long.TryParse(timestamp, out var sent) || Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - sent) > ToleranceSeconds) { throw new CryptographicException("timestamp outside the tolerance"); } var key = Convert.FromBase64String(secret.StartsWith("whsec_") ? secret[6..] : secret); var signed = Encoding.UTF8.GetBytes($"{id}.{timestamp}.").Concat(body).ToArray(); var expected = Encoding.ASCII.GetBytes(Convert.ToBase64String(HMACSHA256.HashData(key, signed))); foreach (var entry in signatures.Split(' ')) { var parts = entry.Split(',', 2); if (parts.Length == 2 && parts[0] == "v1" && CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(parts[1]), expected)) { return JsonDocument.Parse(body); } } throw new CryptographicException("signature does not match"); } } ``` **PHP** ```php TOLERANCE_SECONDS) { throw new RuntimeException("timestamp outside the tolerance"); } $key = base64_decode(preg_replace('/^whsec_/', "", $secret), true); $expected = base64_encode(hash_hmac("sha256", "$id.$timestamp.$body", (string) $key, true)); foreach (explode(" ", $signatures) as $entry) { [$version, $signature] = array_pad(explode(",", $entry, 2), 2, ""); if ($version === "v1" && hash_equals($expected, $signature)) { return json_decode($body, true, flags: JSON_THROW_ON_ERROR); } } throw new RuntimeException("signature does not match"); } // Try it with a delivery: the body on standard input, the three headers in the environment. $event = aigently_unwrap( file_get_contents("php://stdin"), [ "webhook-id" => (string) getenv("WEBHOOK_ID"), "webhook-timestamp" => (string) getenv("WEBHOOK_TIMESTAMP"), "webhook-signature" => (string) getenv("WEBHOOK_SIGNATURE"), ], (string) getenv("AIGENTLY_WEBHOOK_SECRET"), ); echo "verified {$event["event"]} {$event["id"]}\n"; ``` The same function checks a [context lookup](/guides/inbound-calls) request, with the lookup's secret. Receivers made before this signature existed also get `X-Agently-Signature: t=,v1=` — an HMAC-SHA256 of `.` keyed with the secret's text. It keeps working, and both are sent on every delivery. ## Manage receivers from your server A company that integrates for many customers makes a receiver per customer — from code, with a key that has `webhooks:write`. A test key's receivers are test receivers; a live key's are live. The address must be public `https`, and a project holds at most ten. **curl** ```sh #!/bin/sh # Create a webhook receiver. Keep the secret in the answer: it is shown once. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/webhooks" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "url": "https://hooks.aigently.ai/aigently", "events": [ "conversation.ended", "conversation.analyzed" ] }' ``` **JavaScript** ```js // Create a webhook receiver. Keep the secret in the answer: it is shown once. const response = await fetch("https://api.aigently.ai/v1/webhooks", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "url": "https://hooks.aigently.ai/aigently", "events": [ "conversation.ended", "conversation.analyzed" ] }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Create a webhook receiver. Keep the secret in the answer: it is shown once. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/webhooks", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "url": "https://hooks.aigently.ai/aigently", "events": ["conversation.ended", "conversation.analyzed"], }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Create a webhook receiver. Keep the secret in the answer: it is shown once. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "url": "https://hooks.aigently.ai/aigently", "events": [ "conversation.ended", "conversation.analyzed" ] }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/webhooks", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Create a webhook receiver. Keep the secret in the answer: it is shown once. 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 { String body = """ { "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "url": "https://hooks.aigently.ai/aigently", "events": [ "conversation.ended", "conversation.analyzed" ] } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/webhooks")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Create a webhook receiver. Keep the secret in the answer: it is shown once. 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.Post, "https://api.aigently.ai/v1/webhooks") { Content = new StringContent( """ { "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "url": "https://hooks.aigently.ai/aigently", "events": [ "conversation.ended", "conversation.analyzed" ] } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "project_id" => "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "url" => "https://hooks.aigently.ai/aigently", "events" => ["conversation.ended", "conversation.analyzed"], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` The answer carries the receiver's **secret, once**. Read a receiver, change what it hears or switch it off, and delete it, with the same key: **curl** ```sh #!/bin/sh # List webhook receivers curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/webhooks" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List webhook receivers const response = await fetch("https://api.aigently.ai/v1/webhooks", { 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 # List webhook receivers # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/webhooks", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List webhook receivers package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/webhooks", 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 // List webhook receivers 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/webhooks")) .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 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 // List webhook receivers 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/webhooks") { }; 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 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"; ``` **curl** ```sh #!/bin/sh # Change what a receiver hears curl -sS --fail-with-body -X PATCH "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "events": [ "conversation.ended" ], "include_values": false }' ``` **JavaScript** ```js // Change what a receiver hears const response = await fetch("https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "events": [ "conversation.ended" ], "include_values": false }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Change what a receiver hears # pip install httpx import os import httpx response = httpx.patch( "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "events": ["conversation.ended"], "include_values": False, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Change what a receiver hears package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "events": [ "conversation.ended" ], "include_values": false }`) request, err := http.NewRequest("PATCH", "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Change what a receiver hears 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 { String body = """ { "events": [ "conversation.ended" ], "include_values": false } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("PATCH", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Change what a receiver hears 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.Patch, "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c") { Content = new StringContent( """ { "events": [ "conversation.ended" ], "include_values": false } """, Encoding.UTF8, "application/json"), }; 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 "PATCH", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "events" => ["conversation.ended"], "include_values" => false, ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` **curl** ```sh #!/bin/sh # Delete a webhook receiver curl -sS --fail-with-body -X DELETE "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Delete a webhook receiver const response = await fetch("https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c", { method: "DELETE", 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 # Delete a webhook receiver # pip install httpx import os import httpx response = httpx.delete( "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Delete a webhook receiver package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("DELETE", "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c", 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 // Delete a webhook receiver 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/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("DELETE", 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 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 // Delete a webhook receiver 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.Delete, "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c") { }; 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 "DELETE", 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"; ``` A key limited to some agents cannot manage receivers: a receiver belongs to its whole project. ## Change a secret without missing an event Rotating a secret with an overlap keeps the old one signing beside the new one until then: every delivery carries a signature from each, and the standard's libraries — like the function above — accept either. Update your receiver within the overlap, and nothing is ever rejected. **curl** ```sh #!/bin/sh # Change a receiver's secret, keeping the old one for a day curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/rotate-secret" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "keep_previous_for": "24h" }' ``` **JavaScript** ```js // Change a receiver's secret, keeping the old one for a day const response = await fetch("https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/rotate-secret", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "keep_previous_for": "24h" }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Change a receiver's secret, keeping the old one for a day # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/rotate-secret", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "keep_previous_for": "24h", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Change a receiver's secret, keeping the old one for a day package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "keep_previous_for": "24h" }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/rotate-secret", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Change a receiver's secret, keeping the old one for a day 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 { String body = """ { "keep_previous_for": "24h" } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/rotate-secret")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Change a receiver's secret, keeping the old one for a day 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.Post, "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/rotate-secret") { Content = new StringContent( """ { "keep_previous_for": "24h" } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "keep_previous_for" => "24h", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` `keep_previous_for` is `now`, `1h`, `24h` or `7d`. **`now` is the answer to a leak**: the old secret stops at once. In the console, the same choice is **The old secret** in the rotate dialog. ## When deliveries failed Every delivery of the last 30 days, with how each attempt went: **curl** ```sh #!/bin/sh # List what a receiver was sent curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries?status=failed" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List what a receiver was sent const response = await fetch("https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries?status=failed", { 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 # List what a receiver was sent # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "status": "failed", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List what a receiver was sent package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries?status=failed", 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 // List what a receiver was sent 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/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries?status=failed")) .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 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 // List what a receiver was sent 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/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries?status=failed") { }; 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 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"; ``` After your receiver was down, send a failed delivery again with a fresh set of retries. One already waiting is left as it is, and one that was delivered is never sent twice: **curl** ```sh #!/bin/sh # Send a failed delivery again curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries/9e1b3d5f-7a9c-4e2b-8d4f-6a8c0e2b4d6f/resend" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Send a failed delivery again const response = await fetch("https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries/9e1b3d5f-7a9c-4e2b-8d4f-6a8c0e2b4d6f/resend", { method: "POST", 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 # Send a failed delivery again # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries/9e1b3d5f-7a9c-4e2b-8d4f-6a8c0e2b4d6f/resend", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Send a failed delivery again package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries/9e1b3d5f-7a9c-4e2b-8d4f-6a8c0e2b4d6f/resend", 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 // Send a failed delivery again 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/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries/9e1b3d5f-7a9c-4e2b-8d4f-6a8c0e2b4d6f/resend")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("POST", 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 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 // Send a failed delivery again 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.Post, "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries/9e1b3d5f-7a9c-4e2b-8d4f-6a8c0e2b4d6f/resend") { }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => "", ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` Check a receiver end to end with a signed test event: **curl** ```sh #!/bin/sh # Send a test event curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/test" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Send a test event const response = await fetch("https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/test", { method: "POST", 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 # Send a test event # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/test", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Send a test event package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/test", 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 // Send a test event 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/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/test")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("POST", 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 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 // Send a test event 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.Post, "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/test") { }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => "", ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` ## Live and test receivers A receiver is **live** or **test**. Live receivers hear about real conversations; test receivers hear only about conversations made with test keys — appointments an agent books in a test key's chat included. Point a test receiver at a staging server — or use [`aigently listen`](/cli) to get test events on your laptop. ## Personal data Phone numbers, the values a conversation started with and your metadata go only to receivers that have **Include the values the conversation was started with** turned on. A receiver from before this setting gets them only once you turn it on. That means `from_number`, `to_number`, `variables`, `variable_sources` and `metadata`. The fields events carried before the setting existed are sent either way, so the receivers already reading them keep working: `caller`, the caller's number as the phone network gave it, and a handoff's `contact`. ## Delivery - Each delivery has ten seconds in total to be answered, however slowly your server reads. - A failed delivery is retried with growing waits; the console shows every attempt and can send one again. - One slow receiver does not hold up another's deliveries. --- # The event feed > Every event of the last 30 days, in order — to catch up on webhooks you missed, or instead of receiving them at all. Every event the platform sends to [webhook receivers](/guides/webhooks) is also kept for **30 days** in a feed you can read: the same events, with the same `id`s, whether or not anybody received them. Use it to catch up after your receiver was down, or read it instead of running a receiver at all. Reading needs `conversations:read`. **curl** ```sh #!/bin/sh # Read the event feed. Keep the last page's next_cursor and send it back as cursor= next time. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/events?type=conversation.ended&limit=50" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read the event feed. Keep the last page's next_cursor and send it back as cursor= next time. const response = await fetch("https://api.aigently.ai/v1/events?type=conversation.ended&limit=50", { 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 # Read the event feed. Keep the last page's next_cursor and send it back as cursor= next time. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/events", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "type": "conversation.ended", "limit": 50, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read the event feed. Keep the last page's next_cursor and send it back as cursor= next time. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/events?type=conversation.ended&limit=50", 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 // Read the event feed. Keep the last page's next_cursor and send it back as cursor= next time. 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/events?type=conversation.ended&limit=50")) .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 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 // Read the event feed. Keep the last page's next_cursor and send it back as cursor= next time. 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/events?type=conversation.ended&limit=50") { }; 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 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"; ``` ## Read it in order Events come **oldest first**. Read until `has_more` is `false`, keep the last page's `next_cursor`, and next time send it back as `cursor`: you get every event since, once. Events from the last minute wait for a later page, so one still being written is never skipped. Each event is what a receiver would have been sent: ```json { "object": "event", "id": "0f9a7c2e-5b1d-4e8a-9c3f-2d6b8e1a4c7f", "event": "conversation.ended", "created_at": "2026-10-07T09:14:03.120394+00:00", "livemode": true, "revision": 6, "data": { "object": "conversation", "id": "5f0c9a52-…", "status": "completed", "…": "…" } } ``` An event you already received through a webhook has the same `id` here, so keep the ids you have handled and skip them. As with webhooks, keep the conversation with the higher `revision`. ## Narrow it | Parameter | | |---|---| | `type` | One event type, like `conversation.ended`. Repeat it for several. | | `conversation_id` | Only the events about one conversation. | | `created_after` | Only events from this time on — where to start the first time. | ## What a key sees The feed follows the same rules as everything else a key reads: its own projects and agents, and its own side of [test mode](/guides/test-mode). `conversation.transcript` events are listed only for a key with `transcripts:read`. --- # Test mode > Build and test an integration without a phone number, a carrier or credit — and without ever ringing anybody. A **test key** (`ag_test_…`) works like a live one against your real agents, with three differences: its calls ring nobody, it sees only test data, and its events go only to test receivers. ## Test numbers A test key calls only these numbers, and each one plays out a fixed ending over about ten seconds — with the agent's real greeting and your values, the same events a real call sends, and, where the call is answered, its analysis and a short sample recording. | Number | What it plays | Analysis checks | |---|---|---| | `+12025550100` | Answered, talked, and somebody hung up | pass | | `+12025550101` | Answered, talked, and somebody hung up | fail | | `+12025550102` | The line was busy | — | | `+12025550103` | It rang and nobody answered | — | | `+12025550104` | The person rejected the call | — | | `+12025550105` | An answering machine answered, and the agent left its message | — | | `+12025550106` | An answering machine answered, and no message was left | — | | `+12025550107` | The carrier would not put the call through | — | Any other number is refused with `422 test_number_required`. Nothing is dialled and nothing is charged. ## Calls to your agents A test key can also make a call *to* one of your inbound agents, from a test number — the only way to try an agent's [context lookup](/guides/inbound-calls) without a phone: **curl** ```sh #!/bin/sh # Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/test/inbound-calls" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" }' ``` **JavaScript** ```js // Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. const response = await fetch("https://api.aigently.ai/v1/test/inbound-calls", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/test/inbound-calls", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/test/inbound-calls", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. 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 { String body = """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/test/inbound-calls")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. 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.Post, "https://api.aigently.ai/v1/test/inbound-calls") { Content = new StringContent( """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "agent_id" => "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number" => "+12025550100", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` The agent's **test address** is asked, or its sample answer used, and never its live address. The answer says what the lookup made of it, and the call then plays out like any test call. ## Chats A chat with a test key uses the agent's real model, because the reply is the point of testing it, and is charged like any chat. It is marked as a test-key chat on the organization's transactions. ## What stays apart - A test key reads only test-key conversations. A real conversation asked for with a test key is `404`, and a live key never sees test-key conversations. - Test-key conversations go only to **test** webhook receivers, and never count in the console's results or dashboards. The console's call list shows them when **Mode** is set to **Test key**. - They are deleted after 30 days. - A test key makes at most ten test calls a minute. ## Moving to live The same code works with a live key. See [Going live](/going-live) for what changes. --- # Rate limits > How fast a key may call the API, the headers that say how much is left, and what to do at a limit. Every response says which limit it was counted against and how much of it is left. ## The limits | Limit | Default | |---|---| | Reads, per key | 600 a minute | | Writes, per key | 120 a minute | | Chat messages, per key | 1,200 a minute | | Chat messages, per conversation | 20 a minute | | Each of the three above, for all of an organization's keys together | 4 × the per-key number | | Calls at the same time, per organization | 10 | | Calls a day, per organization | 2,000 | | Recording links, per key | 60 a minute and 2,000 a day | | Test calls, per test key | 10 a minute | The deployment's operator can change an organization's limits. ## The headers ```text RateLimit-Policy: "writes";q=120;w=60 RateLimit: "writes";r=87;t=34 ``` `q` is the limit, `w` the window in seconds, `r` what is left in this window and `t` the seconds until it starts again. The format follows the IETF's RateLimit header draft. A `429` also has `Retry-After`, in seconds. ## At a limit | Code | What to do | |---|---| | `rate_limited` | Wait for `Retry-After`, then send the same request again. | | `concurrency_limit_reached` | Wait for calls to finish; `GET /v1/me` shows how many are in progress. Do not keep retrying. | | `daily_limit_reached` | The day's calls are used. Try again after midnight UTC. | | `limits_unavailable` | Something that costs money could not be counted safely just now. Wait for `Retry-After`. | **A retry is never refused for the request it repeats**: a request sent again with its `Idempotency-Key` gets its first answer back before any limit is counted. --- # Safe retries > Send a request again after a timeout without calling anybody twice. Networks fail in the middle of requests. When you did not get an answer you cannot tell whether the call was placed — so send your own id for it, and send it again with the same id. ## The Idempotency-Key header | Request | The header | |---|---| | Place a call | Required. Without it: `400 idempotency_key_required`. | | Start a chat | Optional. The same request again returns the same chat. | | Send a chat message | Optional. The same message again returns the same reply, without asking the agent twice. | Up to 120 characters. **Build it from your own data** — `lead-8812-attempt-2`, not a random string made fresh for each try — so a retry after a crash still carries the same id. The SDKs make a key for each call and send the same one on each of their own retries. Give your own through their idempotency key option, or as the `Idempotency-Key` header itself: either way, yours is the one sent. ## What happens | Situation | Result | |---|---| | Same key, same request | The same conversation as it is now, with the header `Idempotent-Replayed: true`. | | Same key, a different request | `422 idempotency_key_reused`: the agent, the numbers, the values and the metadata are compared. | | Same key, two requests at the same moment | One of them places the call; the other gets that call. | | The call failed after it was saved | A retry returns that failed conversation and never calls again. To call again, use a new key. | A key belongs to its conversation for as long as the conversation exists — reusing last week's key returns last week's call. A test key's ids and a live key's never meet. ## Ending Ending a conversation is always safe to send again: ending one that has already ended returns it. --- # API keys > Organization keys, test and live, what each may do and reach — and the older per-agent chat keys. An API key belongs to your organization. Owners and admins make them on the console's **API keys** page; making one asks for your password again, and every owner is emailed. ## Test and live | | Test key, `ag_test_…` | Live key, `ag_live_…` | |---|---|---| | Calls | Only [test numbers](/guides/test-mode#test-numbers). Nothing rings. | Real phones. | | Conversations it reads | Test-key conversations only. | Real ones only. | | Its events go to | Test receivers. | Live receivers. | | From a browser | Yes — this site's *Try it* uses one. | Never: `403 live_key_in_browser`. | ## What a key may do | Permission | Lets it | |---|---| | `agents:read` | Read agents and their variables. | | `phone_numbers:read` | List the organization's numbers. | | `calls:write` | Place and end calls, and make test calls. | | `chats:write` | Start and continue chats, upload pictures. | | `conversations:read` | Read and sync conversations. | | `transcripts:read` | Read what was said. | | `recordings:read` | Get recording links. Never part of a preset: tick it on its own. | The presets — *Read only*, *Outbound calling* and *Chat* — are starting points. A key asking for something it may not do gets `403 permission_denied`, naming the permission. ## What a key reaches A key reaches every project, or only the projects you choose — and within them, if you like, only some agents. Anything outside is `404`, exactly as if it did not exist. `GET /v1/me` says what a key is and what it reaches: **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 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 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"; ``` ## Where a key works from A key can be limited to your servers' addresses when it is made: single addresses like `203.0.113.7`, or ranges like `198.51.100.0/24`, IPv4 or IPv6, up to 20. A request from anywhere else is refused with `403 address_not_allowed`, and `detail` names the address it came from — the address your server is seen from, after any proxy of your own. A key made without addresses works from anywhere. `reach.addresses` in `GET /v1/me` lists them; they cannot be changed afterwards, so a server that moves needs a new key. ## Rotating and revoking **Rotate** a key that may have leaked, or when somebody who knew it leaves: it gets a new secret, and the old one keeps working for the time you choose — none, an hour, a day or a week — so your servers can be updated first. **Revoke** stops a key on its very next request. An organization can have 25 keys in use. A key whose maker has left the organization is flagged, never cancelled for you. ## See what a key has been doing Each key's **Requests** page in the console, in the key's menu under **API keys**, lists every request it made in the last 30 days: the method, the path, the status, the error `code` of a refusal, how long the answer took, and the request id. Use it to see why a request was refused. Request bodies are never kept. ## If a key leaks Rotate it, or revoke it, on the API keys page. If the key was pushed to a public repository on GitHub, it may already be revoked: GitHub's secret scanning recognises our keys by their shape, and reports them to us. A working key found that way is revoked within seconds — a rotated key's old secret just stops — and every owner of the organization is emailed with where it was found. Make a new key for the servers that used it, and remove the secret from the repository, history included. ## The older chat keys Before organization keys, each agent had its own **secret key** (`ag_sk_…`) on its **Connect → Server API** tab, for chatting with that one agent. Those keys keep working and can be rotated, but reach nothing else. Anything new should use an API key. --- # Signing visitors in the widget > Hand the chat widget what your server knows about a signed-in visitor, signed so the agent can rely on it. The chat widget on your site can be given values for the agent's [variables](/guides/variables). Values a page collects on its own are whatever the visitor typed into the address bar; values your **server** signs are ones the agent can act on. ## How it works 1. Under **Trusted visitor details** on the agent's **Connect → Website widget** tab, choose **Create a signing secret**. Keep it on your server. 2. For each page load, your server signs the values it knows to be true — a name, a customer id, a plan — into a short-lived token. 3. The page hands the token to the widget: `Aigently.identify(token)`, or a `data-identity` line on the widget's snippet. 4. The platform checks the signature before the values reach the agent. A value from a token is recorded as `identity_token` in the conversation's `variable_sources`. ## Sign a token The token is `v1..`: the payload is JSON — `{"exp": , "v": {…}}` — in base64url, and the signature an HMAC-SHA256 of `v1.` with the secret, also base64url. Here it is in your language: **curl** ```sh #!/bin/sh # Sign an identity token by hand with openssl, to try the chat widget before your server does it. # The secret is in AIGENTLY_IDENTITY_SECRET; the token lives for five minutes. set -eu base64url() { base64 | tr -d '\n=' | tr '+/' '-_'; } expires=$(($(date +%s) + 300)) body="$(printf '{"exp":%s,"v":{"first_name":"Sara","customer_id":"C-1042"}}' "$expires" | base64url)" signature="$(printf 'v1.%s' "$body" \ | openssl dgst -sha256 -hmac "$AIGENTLY_IDENTITY_SECRET" -binary | base64url)" echo "v1.$body.$signature" ``` **JavaScript** ```js // Sign what your server knows about a visitor, for the chat widget. Mint one per page load and // hand it to the page, which passes it on with Aigently.identify(token) or data-identity. import { createHmac } from "node:crypto"; // `values` are strings, at most 20 of them. A token lives for at most an hour. export function signIdentity(values, secret, lifetimeSeconds = 300) { const payload = { exp: Math.floor(Date.now() / 1000) + lifetimeSeconds, v: values }; const body = Buffer.from(JSON.stringify(payload)).toString("base64url"); const signature = createHmac("sha256", secret).update(`v1.${body}`).digest("base64url"); return `v1.${body}.${signature}`; } console.log( signIdentity({ first_name: "Sara", customer_id: "C-1042" }, process.env.AIGENTLY_IDENTITY_SECRET), ); ``` **Python** ```python # Sign what your server knows about a visitor, for the chat widget. Mint one per page load and # hand it to the page, which passes it on with Aigently.identify(token) or data-identity. import base64 import hashlib import hmac import json import os import time def _b64url(raw: bytes) -> str: return base64.urlsafe_b64encode(raw).decode().rstrip("=") def sign_identity(values: dict[str, str], secret: str, lifetime: int = 300) -> str: """`values` are strings, at most 20 of them. A token lives for at most an hour.""" payload = json.dumps({"exp": int(time.time()) + lifetime, "v": values}, separators=(",", ":")) body = _b64url(payload.encode()) signature = hmac.new(secret.encode(), f"v1.{body}".encode(), hashlib.sha256).digest() return f"v1.{body}.{_b64url(signature)}" if __name__ == "__main__": print( sign_identity( {"first_name": "Sara", "customer_id": "C-1042"}, os.environ["AIGENTLY_IDENTITY_SECRET"], ) ) ``` **Go** ```go // Sign what your server knows about a visitor, for the chat widget. Mint one per page load and // hand it to the page, which passes it on with Aigently.identify(token) or data-identity. package main import ( "crypto/hmac" "crypto/sha256" "encoding/base64" "encoding/json" "fmt" "os" "time" ) // SignIdentity signs values, which are at most 20 strings. A token lives for at most an hour. func SignIdentity(values map[string]string, secret string, lifetime time.Duration) (string, error) { payload, err := json.Marshal(struct { Exp int64 `json:"exp"` Values map[string]string `json:"v"` }{time.Now().Add(lifetime).Unix(), values}) if err != nil { return "", err } body := base64.RawURLEncoding.EncodeToString(payload) mac := hmac.New(sha256.New, []byte(secret)) mac.Write([]byte("v1." + body)) return "v1." + body + "." + base64.RawURLEncoding.EncodeToString(mac.Sum(nil)), nil } func main() { token, err := SignIdentity( map[string]string{"first_name": "Sara", "customer_id": "C-1042"}, os.Getenv("AIGENTLY_IDENTITY_SECRET"), 5*time.Minute, ) if err != nil { panic(err) } fmt.Println(token) } ``` **Java** ```java // Sign what your server knows about a visitor, for the chat widget. Mint one per page load and // hand it to the page, which passes it on with Aigently.identify(token) or data-identity. import java.nio.charset.StandardCharsets; import java.util.Base64; import java.util.Map; import java.util.stream.Collectors; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; public class Main { /** `values` are at most 20 strings. A token lives for at most an hour. */ static String signIdentity(Map values, String secret, long lifetimeSeconds) throws Exception { long expires = System.currentTimeMillis() / 1000 + lifetimeSeconds; String variables = values.entrySet().stream() .map(entry -> quote(entry.getKey()) + ":" + quote(entry.getValue())) .collect(Collectors.joining(",")); String payload = "{\"exp\":" + expires + ",\"v\":{" + variables + "}}"; Base64.Encoder base64url = Base64.getUrlEncoder().withoutPadding(); String body = base64url.encodeToString(payload.getBytes(StandardCharsets.UTF_8)); Mac mac = Mac.getInstance("HmacSHA256"); mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256")); byte[] signature = mac.doFinal(("v1." + body).getBytes(StandardCharsets.UTF_8)); return "v1." + body + "." + base64url.encodeToString(signature); } /** A JSON string. Your JSON library does the same. */ static String quote(String text) { StringBuilder out = new StringBuilder("\""); for (char c : text.toCharArray()) { if (c == '"' || c == '\\') { out.append('\\').append(c); } else if (c < 0x20) { out.append(String.format("\\u%04x", (int) c)); } else { out.append(c); } } return out.append('"').toString(); } public static void main(String[] args) throws Exception { System.out.println(signIdentity( Map.of("first_name", "Sara", "customer_id", "C-1042"), System.getenv("AIGENTLY_IDENTITY_SECRET"), 300)); } } ``` **C#** ```csharp // Sign what your server knows about a visitor, for the chat widget. Mint one per page load and // hand it to the page, which passes it on with Aigently.identify(token) or data-identity. using System.Security.Cryptography; using System.Text; using System.Text.Json; Console.WriteLine(Identity.Sign( new Dictionary { ["first_name"] = "Sara", ["customer_id"] = "C-1042" }, Environment.GetEnvironmentVariable("AIGENTLY_IDENTITY_SECRET") ?? "", TimeSpan.FromMinutes(5))); static class Identity { // `values` are at most 20 strings. A token lives for at most an hour. public static string Sign(IReadOnlyDictionary values, string secret, TimeSpan lifetime) { // Written field by field, which needs no reflection and so works in a trimmed app too. using var payload = new MemoryStream(); using (var json = new Utf8JsonWriter(payload)) { json.WriteStartObject(); json.WriteNumber("exp", DateTimeOffset.UtcNow.Add(lifetime).ToUnixTimeSeconds()); json.WriteStartObject("v"); foreach (var (name, value) in values) { json.WriteString(name, value); } json.WriteEndObject(); json.WriteEndObject(); } var body = Base64Url(payload.ToArray()); var signature = HMACSHA256.HashData( Encoding.UTF8.GetBytes(secret), Encoding.UTF8.GetBytes($"v1.{body}")); return $"v1.{body}.{Base64Url(signature)}"; } static string Base64Url(byte[] raw) => Convert.ToBase64String(raw).TrimEnd('=').Replace('+', '-').Replace('/', '_'); } ``` **PHP** ```php time() + $lifetime, "v" => (object) $values], JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR, ); $body = aigently_base64url($payload); $signature = hash_hmac("sha256", "v1.$body", $secret, true); return "v1.$body." . aigently_base64url($signature); } echo aigently_sign_identity( ["first_name" => "Sara", "customer_id" => "C-1042"], (string) getenv("AIGENTLY_IDENTITY_SECRET"), ), "\n"; ``` ## Rules - **Values are text**, at most 20 of them. A value longer than 500 characters is cut. - **A token lives for at most an hour.** Mint one per page load, five minutes is plenty. A token claiming to live longer is refused. - **A signature proves where the values came from, not who is at the keyboard.** A page that signs the wrong person's name signs the wrong person's name. Treat these as personalisation, backed by your own login. - **`phone` is special**: a signed `phone` tells the platform who the visitor is, so their chats join the history of calls from that number. --- # Credit and billing > Read your organization's credit balance, every charge and every credit added, and what each conversation cost. Conversations are paid for in **credits**, from your organization's balance. Reading it needs `billing:read`. It is the same balance and the same history as the console's Billing page. ## The balance **curl** ```sh #!/bin/sh # Read the credit balance curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/billing/balance" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read the credit balance const response = await fetch("https://api.aigently.ai/v1/billing/balance", { 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 # Read the credit balance # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/billing/balance", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read the credit balance package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/billing/balance", 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 // Read the credit balance 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/billing/balance")) .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 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 // Read the credit balance 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/billing/balance") { }; 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 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"; ``` - `balance` is the credit on the account, and `free_left` how much of it is free credit not yet spent. - `available` is what can still be spent: the balance, less what conversations in progress are holding, plus any credit line. - `spent_this_month` counts from `since`, the first of the month in UTC. - `suspended` is `true` while new conversations are refused until credit is added, and `unlimited` is `true` when the organization is never refused. `enforced` says whether running out stops conversations at all: when it is `false`, credit is counted and nothing is refused. The balance is the organization's, whichever key reads it. ## The credit history **curl** ```sh #!/bin/sh # List what was charged curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/billing/transactions?limit=20" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List what was charged const response = await fetch("https://api.aigently.ai/v1/billing/transactions?limit=20", { 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 # List what was charged # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/billing/transactions", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "limit": 20, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List what was charged package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/billing/transactions?limit=20", 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 // List what was charged 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/billing/transactions?limit=20")) .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 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 // List what was charged 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/billing/transactions?limit=20") { }; 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 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"; ``` Every movement of credit, newest first: each conversation's charge, each analysis, credit added and refunds. `amount` is negative when credit was spent and positive when it was added, and `balance_after` is the balance it left. Filter by `conversation_id`, by `kind` (repeat it for several) or by `created_after`, and page with `next_cursor` as everywhere else. Amounts are in credits, to six decimal places. A chat is charged as it goes, so one chat can have several charges. For one conversation's total, ask for the conversation with [`include=cost`](/guides/conversations#what-it-cost). The history outlives what it charged for: a deleted conversation's charges stay, under its id. ## What a key sees - **A key limited to some projects** reads their charges alone. Credit added to the organization belongs to no project, so it is not in that key's history. - **A test key** reads what test keys spent: their chats, which use the agent's real model and are charged like any chat. Test calls cost nothing. `livemode` on each transaction says which kind of key it was. - **Another organization's history** is never reachable, whatever the key. --- # Phone numbers > List your organization's phone numbers, and choose the agent each one belongs to. Your phone numbers are added in the console, on the **Telephony** page, where each is connected to your carrier. Through the API you can list them and choose which agent each one belongs to. ## List them **curl** ```sh #!/bin/sh # List phone numbers curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/phone-numbers" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List phone numbers const response = await fetch("https://api.aigently.ai/v1/phone-numbers", { 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 # List phone numbers # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/phone-numbers", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List phone numbers package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/phone-numbers", 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 // List phone numbers 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/phone-numbers")) .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 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 // List phone numbers 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/phone-numbers") { }; 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 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"; ``` This needs `phone_numbers:read`. Each number says which way it carries calls, whether it is in service, and the agent it belongs to. `can_receive_calls` and `can_place_calls` say whether it works right now: a number still waiting to be verified, or switched off, cannot. Use a number that can place calls as `phone_number_id` when you [place a call](/guides/outbound-calls). ## Point a number at an agent **curl** ```sh #!/bin/sh # Point a number at an agent. With a live key: a phone number is real. curl -sS --fail-with-body -X PATCH "https://api.aigently.ai/v1/phone-numbers/7a9c1e3f-5b7d-4f9a-8c2e-4d6f8a0c2e4a" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f" }' ``` **JavaScript** ```js // Point a number at an agent. With a live key: a phone number is real. const response = await fetch("https://api.aigently.ai/v1/phone-numbers/7a9c1e3f-5b7d-4f9a-8c2e-4d6f8a0c2e4a", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f" }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Point a number at an agent. With a live key: a phone number is real. # pip install httpx import os import httpx response = httpx.patch( "https://api.aigently.ai/v1/phone-numbers/7a9c1e3f-5b7d-4f9a-8c2e-4d6f8a0c2e4a", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Point a number at an agent. With a live key: a phone number is real. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f" }`) request, err := http.NewRequest("PATCH", "https://api.aigently.ai/v1/phone-numbers/7a9c1e3f-5b7d-4f9a-8c2e-4d6f8a0c2e4a", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Point a number at an agent. With a live key: a phone number is real. 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 { String body = """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f" } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/phone-numbers/7a9c1e3f-5b7d-4f9a-8c2e-4d6f8a0c2e4a")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("PATCH", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Point a number at an agent. With a live key: a phone number is real. 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.Patch, "https://api.aigently.ai/v1/phone-numbers/7a9c1e3f-5b7d-4f9a-8c2e-4d6f8a0c2e4a") { Content = new StringContent( """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f" } """, Encoding.UTF8, "application/json"), }; 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 "PATCH", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "agent_id" => "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` This needs `phone_numbers:write`, a permission no starting point in the console includes, and a **live key**: a phone number is real, so a test key is refused with `403 live_key_required`. - A number that only receives calls rings its agent, so the agent must be an inbound agent that answers phone calls. - A number that only places calls is the caller ID of an outbound agent. - A number that does both can belong to either. An inbound agent answers it; an outbound agent calls from it, and calls back to it go where that agent's **When somebody calls back** setting says. - The agent must be in the number's project. A mismatch is refused with `409 number_agent_mismatch`, and `detail` says what to change. Send `"agent_id": null` to leave the number with no agent. The change takes effect on the next call; a call already in progress is not affected. If the number's previous agent made calls from it, that agent keeps calling from it: only the owner changes. Each change is recorded in your organization's audit log under the key. ## What a key sees A key limited to some projects lists their numbers alone. A key limited to some agents lists the numbers those agents own or call from, and moves a number only between those agents. --- # Campaigns > Call a list of people at a pace you set, only in calling hours, and hear how each call went. A campaign is a list of people for an outbound agent to call, at the pace you set and only in the hours you allow. It is the same campaign the console shows on the agent's **Campaigns** tab: one you start through the API, a colleague can pause in the console, and the other way round. Campaigns call real people, so making or changing one needs a **live key** with `campaigns:write`, and reading them needs `campaigns:read`. A test key reads no campaigns. To try your integration first, [schedule single calls](/guides/outbound-calls#schedule-a-call-for-later) to the test numbers. ## Create one **curl** ```sh #!/bin/sh # Create a campaign. With a live key: a campaign calls real people. It is a draft until you start it. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/campaigns" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ -H "Idempotency-Key: reminders-october" \ --json '{ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "name": "Visit reminders, October", "calling_hours": { "start_hour": 9, "end_hour": 18, "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "contacts": [ { "to_number": "+12025550123", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" }, { "to_number": "+12025550124", "variables": { "first_name": "Omar" }, "timezone": "America/Chicago", "external_id": "lead-20932" } ] }' ``` **JavaScript** ```js // Create a campaign. With a live key: a campaign calls real people. It is a draft until you start it. const response = await fetch("https://api.aigently.ai/v1/campaigns", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "reminders-october", }, body: JSON.stringify({ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "name": "Visit reminders, October", "calling_hours": { "start_hour": 9, "end_hour": 18, "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "contacts": [ { "to_number": "+12025550123", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" }, { "to_number": "+12025550124", "variables": { "first_name": "Omar" }, "timezone": "America/Chicago", "external_id": "lead-20932" } ] }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Create a campaign. With a live key: a campaign calls real people. It is a draft until you start it. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/campaigns", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", "Idempotency-Key": "reminders-october", }, json={ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "name": "Visit reminders, October", "calling_hours": { "start_hour": 9, "end_hour": 18, "days": ["mon", "tue", "wed", "thu", "fri"], }, "contacts": [{"to_number": "+12025550123", "variables": {"first_name": "Sara"}, "metadata": {"crm_lead_id": "L-20931"}, "external_id": "lead-20931"}, {"to_number": "+12025550124", "variables": {"first_name": "Omar"}, "timezone": "America/Chicago", "external_id": "lead-20932"}], }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Create a campaign. With a live key: a campaign calls real people. It is a draft until you start it. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "name": "Visit reminders, October", "calling_hours": { "start_hour": 9, "end_hour": 18, "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "contacts": [ { "to_number": "+12025550123", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" }, { "to_number": "+12025550124", "variables": { "first_name": "Omar" }, "timezone": "America/Chicago", "external_id": "lead-20932" } ] }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/campaigns", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") request.Header.Set("Idempotency-Key", "reminders-october") 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 // Create a campaign. With a live key: a campaign calls real people. It is a draft until you start it. 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 { String body = """ { "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "name": "Visit reminders, October", "calling_hours": { "start_hour": 9, "end_hour": 18, "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "contacts": [ { "to_number": "+12025550123", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" }, { "to_number": "+12025550124", "variables": { "first_name": "Omar" }, "timezone": "America/Chicago", "external_id": "lead-20932" } ] } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/campaigns")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .header("Idempotency-Key", "reminders-october") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Create a campaign. With a live key: a campaign calls real people. It is a draft until you start it. 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.Post, "https://api.aigently.ai/v1/campaigns") { Content = new StringContent( """ { "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "name": "Visit reminders, October", "calling_hours": { "start_hour": 9, "end_hour": 18, "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "contacts": [ { "to_number": "+12025550123", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" }, { "to_number": "+12025550124", "variables": { "first_name": "Omar" }, "timezone": "America/Chicago", "external_id": "lead-20932" } ] } """, Encoding.UTF8, "application/json"), }; request.Headers.Add("Idempotency-Key", "reminders-october"); 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", "Idempotency-Key: reminders-october", ], CURLOPT_POSTFIELDS => json_encode([ "agent_id" => "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "name" => "Visit reminders, October", "calling_hours" => [ "start_hour" => 9, "end_hour" => 18, "days" => ["mon", "tue", "wed", "thu", "fri"], ], "contacts" => [ [ "to_number" => "+12025550123", "variables" => [ "first_name" => "Sara", ], "metadata" => [ "crm_lead_id" => "L-20931", ], "external_id" => "lead-20931", ], [ "to_number" => "+12025550124", "variables" => [ "first_name" => "Omar", ], "timezone" => "America/Chicago", "external_id" => "lead-20932", ], ], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` Each contact is one person: `to_number`, their `variables`, and if you like their `timezone`, your own `metadata` and an `external_id`. Everything is checked before anything is made. A number the platform does not call, the same number twice, a time zone that is not one, or a value that does not fit the agent is refused with `validation_failed`, and `errors` names each contact by its place in the list — `contacts[3].variables.renewal_date`. Up to 1,000 contacts go in one request; send the rest as [more people](#add-more-people). **`Idempotency-Key` is required.** A retry with the same key returns the campaign the first attempt made, and never makes a second one that would call everybody twice. See [Safe retries](/guides/idempotency). | Field | What it is | |---|---| | `pacing` | `max_concurrent` calls at once, `dials_per_minute`, `max_attempts` for each person, and `retry_backoff_minutes` between tries. | | `calling_hours` | `start_hour`, `end_hour` and `days`, read in each contact's own `timezone` — or your organization's, for a contact without one. | | `voicemail` | `hang_up` when a machine answers, or `leave_message` with the `message` to leave. | | `callbacks` | Whether a person may ask the agent to call back at a time of their own. | | `phone_number_id` | Which of the agent's numbers to call from. The agent's own unless you say. | | `start`, `start_at` | Start now, or at a moment you choose. Leave both out to start it later. | A campaign is a `draft` until it starts. Starting checks that it can place a call: the agent is published, it has a number to call from, and every contact has the values the agent says out loud — other than a field with a default, which fills in, or one that is not required. It also needs somebody on its list: a campaign started with no contacts would finish at once, so it is refused with `campaign_empty`. To send the contacts in batches, create it as a draft, add them, then start it. A campaign with a `start_at` may be empty until then. If nobody is on its list when the time comes, it starts and waits for its first contacts instead of finishing. ## Start, pause, resume and cancel **curl** ```sh #!/bin/sh # Start a campaign curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/start" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Start a campaign const response = await fetch("https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/start", { method: "POST", 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 # Start a campaign # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/start", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Start a campaign package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/start", 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 // Start a campaign 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/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/start")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("POST", 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 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 // Start a campaign 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.Post, "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/start") { }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => "", ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` **curl** ```sh #!/bin/sh # Pause a campaign. Calls in progress carry on; nobody new is called until you resume it. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/pause" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Pause a campaign. Calls in progress carry on; nobody new is called until you resume it. const response = await fetch("https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/pause", { method: "POST", 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 # Pause a campaign. Calls in progress carry on; nobody new is called until you resume it. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/pause", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Pause a campaign. Calls in progress carry on; nobody new is called until you resume it. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/pause", 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 // Pause a campaign. Calls in progress carry on; nobody new is called until you resume it. 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/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/pause")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("POST", 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 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 // Pause a campaign. Calls in progress carry on; nobody new is called until you resume it. 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.Post, "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/pause") { }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => "", ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` **curl** ```sh #!/bin/sh # Resume a campaign curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/resume" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "reset_attempts": false }' ``` **JavaScript** ```js // Resume a campaign const response = await fetch("https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/resume", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "reset_attempts": false }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Resume a campaign # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/resume", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "reset_attempts": False, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Resume a campaign package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "reset_attempts": false }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/resume", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Resume a campaign 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 { String body = """ { "reset_attempts": false } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/resume")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Resume a campaign 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.Post, "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/resume") { Content = new StringContent( """ { "reset_attempts": false } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "reset_attempts" => false, ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` **curl** ```sh #!/bin/sh # Cancel a campaign. For good: nobody else on the list is called. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/cancel" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Cancel a campaign. For good: nobody else on the list is called. const response = await fetch("https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/cancel", { method: "POST", 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 # Cancel a campaign. For good: nobody else on the list is called. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/cancel", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Cancel a campaign. For good: nobody else on the list is called. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/cancel", 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 // Cancel a campaign. For good: nobody else on the list is called. 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/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/cancel")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("POST", 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 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 // Cancel a campaign. For good: nobody else on the list is called. 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.Post, "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/cancel") { }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => "", ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` Pausing stops new calls. Calls in progress carry on, and resuming picks up where it stopped; send `reset_attempts: true` to give everybody not reached so far every try back. Cancelling stops it for good. Each answers with the campaign, and one that has already happened answers it as it is, so a retry is harmless. A campaign that has finished — `completed` or `cancelled` — answers `campaign_finished`. A campaign can pause itself, too: when your organization's calls for the day are used up, or when calls cannot be placed at all. `paused_reason` says why, and resuming is your decision. While the deployment has phone calls switched off, creating, starting and resuming a campaign are refused with `feature_disabled`. Pausing and cancelling still work. ## Add more people **curl** ```sh #!/bin/sh # Add people to a campaign. A number the campaign already holds is skipped, so sending a batch again is safe. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "contacts": [ { "to_number": "+12025550125", "variables": { "first_name": "Lina" }, "external_id": "lead-20933" } ] }' ``` **JavaScript** ```js // Add people to a campaign. A number the campaign already holds is skipped, so sending a batch again is safe. const response = await fetch("https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "contacts": [ { "to_number": "+12025550125", "variables": { "first_name": "Lina" }, "external_id": "lead-20933" } ] }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Add people to a campaign. A number the campaign already holds is skipped, so sending a batch again is safe. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "contacts": [{"to_number": "+12025550125", "variables": {"first_name": "Lina"}, "external_id": "lead-20933"}], }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Add people to a campaign. A number the campaign already holds is skipped, so sending a batch again is safe. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "contacts": [ { "to_number": "+12025550125", "variables": { "first_name": "Lina" }, "external_id": "lead-20933" } ] }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Add people to a campaign. A number the campaign already holds is skipped, so sending a batch again is safe. 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 { String body = """ { "contacts": [ { "to_number": "+12025550125", "variables": { "first_name": "Lina" }, "external_id": "lead-20933" } ] } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Add people to a campaign. A number the campaign already holds is skipped, so sending a batch again is safe. 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.Post, "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts") { Content = new StringContent( """ { "contacts": [ { "to_number": "+12025550125", "variables": { "first_name": "Lina" }, "external_id": "lead-20933" } ] } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "contacts" => [ [ "to_number" => "+12025550125", "variables" => [ "first_name" => "Lina", ], "external_id" => "lead-20933", ], ], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` A campaign that is a draft, running or paused takes more contacts, and a running one calls them in its next calling hours. A number the campaign already holds is skipped and listed in `already_in_campaign`, so sending a batch again is safe, even while the first is still being added. `+15550100` and `15550100` are the same number. A campaign completes once nobody is left to call; after that, start a new one. ## See how it went **curl** ```sh #!/bin/sh # Read a campaign and its progress curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read a campaign and its progress const response = await fetch("https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b", { 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 # Read a campaign and its progress # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read a campaign and its progress package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b", 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 // Read a campaign and its progress 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/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b")) .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 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 // Read a campaign and its progress 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/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b") { }; 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 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"; ``` `contacts` counts the people in each state. List them, with how it went for each: **curl** ```sh #!/bin/sh # See how each call in a campaign went curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts?status=done" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // See how each call in a campaign went const response = await fetch("https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts?status=done", { 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 # See how each call in a campaign went # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "status": "done", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // See how each call in a campaign went package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts?status=done", 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 // See how each call in a campaign went 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/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts?status=done")) .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 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 // See how each call in a campaign went 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/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts?status=done") { }; 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 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"; ``` | `status` | What it means | |---|---| | `queued` | Waiting for their turn, or for their next try at `next_attempt_at`. | | `dialing` | On a call now. | | `done` | Reached — or a message was left on their machine. | | `exhausted` | Every try was used without reaching them. | | `failed` | Not called: the platform refused, and `error` says why — a number on your [do-not-call list](/guides/outbound-calls#numbers-that-must-not-be-called), for one. | `conversation_id` is their latest conversation. Every conversation with them carries their `metadata`, their `external_id` and the `campaign_id`, so a [webhook](/guides/webhooks) about it can be tied back to its lead. All your campaigns, newest first: **curl** ```sh #!/bin/sh # List campaigns curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/campaigns?limit=10" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List campaigns const response = await fetch("https://api.aigently.ai/v1/campaigns?limit=10", { 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 # List campaigns # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/campaigns", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "limit": 10, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List campaigns package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/campaigns?limit=10", 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 // List campaigns 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/campaigns?limit=10")) .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 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 // List campaigns 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/campaigns?limit=10") { }; 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 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"; ``` ## Hear about it Five events, sent to live receivers only: | Event | When | |---|---| | `campaign.started` | It started calling — at once, at its start time, or again after a pause. | | `campaign.paused` | Paused by somebody, or by itself, with `paused_reason`. | | `campaign.completed` | Nobody is left to call. | | `campaign.cancelled` | Stopped for good. | | `campaign.contact_finished` | One person's final result: `done`, `exhausted` or `failed`. | Each carries the campaign, or the contact, as the API reads it. A contact's number, values and metadata are left out for a receiver that does not include values, as they are for conversations. A campaign belongs to your organization, not to the key that made it: revoking the key does not stop it. Pause or cancel it instead. --- # Contacts > Keep each project's phonebook in step with your own systems, by number. Each project has a phonebook: the people it calls, one entry per number, with the details an agent may say about them. It is the phonebook the console shows, and what it holds reaches two places — a campaign started from it in the console, and an inbound call whose agent [fills its fields from the phonebook](/guides/inbound-calls#fill-fields-from-the-phonebook). Reading it needs `contacts:read`; changing it needs `contacts:write` and a **live key**, because these are real people. A test key reads nobody. A phonebook belongs to its whole project, so a key limited to some agents cannot reach it. ## Add someone **curl** ```sh #!/bin/sh # Add someone to the phonebook. With a live key: the phonebook holds real people. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/contacts" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "phone": "+12025550131", "name": "Sara Haddad", "attributes": { "first_name": "Sara", "member_since": "2023" }, "timezone": "America/New_York" }' ``` **JavaScript** ```js // Add someone to the phonebook. With a live key: the phonebook holds real people. const response = await fetch("https://api.aigently.ai/v1/contacts", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "phone": "+12025550131", "name": "Sara Haddad", "attributes": { "first_name": "Sara", "member_since": "2023" }, "timezone": "America/New_York" }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Add someone to the phonebook. With a live key: the phonebook holds real people. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/contacts", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "phone": "+12025550131", "name": "Sara Haddad", "attributes": { "first_name": "Sara", "member_since": "2023", }, "timezone": "America/New_York", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Add someone to the phonebook. With a live key: the phonebook holds real people. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "phone": "+12025550131", "name": "Sara Haddad", "attributes": { "first_name": "Sara", "member_since": "2023" }, "timezone": "America/New_York" }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/contacts", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Add someone to the phonebook. With a live key: the phonebook holds real people. 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 { String body = """ { "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "phone": "+12025550131", "name": "Sara Haddad", "attributes": { "first_name": "Sara", "member_since": "2023" }, "timezone": "America/New_York" } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/contacts")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Add someone to the phonebook. With a live key: the phonebook holds real people. 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.Post, "https://api.aigently.ai/v1/contacts") { Content = new StringContent( """ { "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "phone": "+12025550131", "name": "Sara Haddad", "attributes": { "first_name": "Sara", "member_since": "2023" }, "timezone": "America/New_York" } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "project_id" => "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "phone" => "+12025550131", "name" => "Sara Haddad", "attributes" => [ "first_name" => "Sara", "member_since" => "2023", ], "timezone" => "America/New_York", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` | Field | What it is | |---|---| | `phone` | Their number, in international format. One entry per number in a project. | | `name` | What the console calls them. The agent never says it — it says what its placeholders take. | | `attributes` | What an agent may say about them. Its `{{placeholders}}` take these by name: `first_name` fills `{{first_name}}`. Kept as text — `3` as `"3"`, `true` as `"yes"`. | | `timezone` | Where they are, like `Asia/Riyadh`: a campaign's calling hours are read there. | A number already in the project's phonebook is `409 contact_exists`. To add or update many people at once, [import them](#import-a-list). ## Find someone, and change them **curl** ```sh #!/bin/sh # Find someone in the phonebook by their number curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/contacts?phone=+12025550131" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Find someone in the phonebook by their number const response = await fetch("https://api.aigently.ai/v1/contacts?phone=+12025550131", { 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 # Find someone in the phonebook by their number # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/contacts", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "phone": "+12025550131", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Find someone in the phonebook by their number package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/contacts?phone=+12025550131", 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 // Find someone in the phonebook by their number 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/contacts?phone=+12025550131")) .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 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 // Find someone in the phonebook by their number 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/contacts?phone=+12025550131") { }; 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 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"; ``` **curl** ```sh #!/bin/sh # Read a contact curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read a contact const response = await fetch("https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d", { 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 # Read a contact # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read a contact package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d", 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 // Read a contact 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/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d")) .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 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 // Read a contact 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/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d") { }; 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 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"; ``` **curl** ```sh #!/bin/sh # Change a contact. attributes is replaced whole: send every one they should have. curl -sS --fail-with-body -X PATCH "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "attributes": { "first_name": "Sara", "member_since": "2021" } }' ``` **JavaScript** ```js // Change a contact. attributes is replaced whole: send every one they should have. const response = await fetch("https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "attributes": { "first_name": "Sara", "member_since": "2021" } }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Change a contact. attributes is replaced whole: send every one they should have. # pip install httpx import os import httpx response = httpx.patch( "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "attributes": { "first_name": "Sara", "member_since": "2021", }, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Change a contact. attributes is replaced whole: send every one they should have. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "attributes": { "first_name": "Sara", "member_since": "2021" } }`) request, err := http.NewRequest("PATCH", "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Change a contact. attributes is replaced whole: send every one they should have. 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 { String body = """ { "attributes": { "first_name": "Sara", "member_since": "2021" } } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("PATCH", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Change a contact. attributes is replaced whole: send every one they should have. 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.Patch, "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d") { Content = new StringContent( """ { "attributes": { "first_name": "Sara", "member_since": "2021" } } """, Encoding.UTF8, "application/json"), }; 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 "PATCH", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "attributes" => [ "first_name" => "Sara", "member_since" => "2021", ], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` A change keeps every field you do not send. `attributes` is replaced whole, so send all of them. A campaign already made keeps the details it copied; the next campaign and the next call read the new ones. ## Import a list **curl** ```sh #!/bin/sh # Import a list into the phonebook. Matched by number: people already there are updated, so sending it again is safe. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/contacts/import" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "contacts": [ { "phone": "+12025550132", "name": "Omar Nasser", "attributes": { "first_name": "Omar" } }, { "phone": "+12025550133", "name": "Lina Saleh", "attributes": { "first_name": "Lina" } } ] }' ``` **JavaScript** ```js // Import a list into the phonebook. Matched by number: people already there are updated, so sending it again is safe. const response = await fetch("https://api.aigently.ai/v1/contacts/import", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "contacts": [ { "phone": "+12025550132", "name": "Omar Nasser", "attributes": { "first_name": "Omar" } }, { "phone": "+12025550133", "name": "Lina Saleh", "attributes": { "first_name": "Lina" } } ] }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Import a list into the phonebook. Matched by number: people already there are updated, so sending it again is safe. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/contacts/import", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "contacts": [{"phone": "+12025550132", "name": "Omar Nasser", "attributes": {"first_name": "Omar"}}, {"phone": "+12025550133", "name": "Lina Saleh", "attributes": {"first_name": "Lina"}}], }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Import a list into the phonebook. Matched by number: people already there are updated, so sending it again is safe. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "contacts": [ { "phone": "+12025550132", "name": "Omar Nasser", "attributes": { "first_name": "Omar" } }, { "phone": "+12025550133", "name": "Lina Saleh", "attributes": { "first_name": "Lina" } } ] }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/contacts/import", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Import a list into the phonebook. Matched by number: people already there are updated, so sending it again is safe. 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 { String body = """ { "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "contacts": [ { "phone": "+12025550132", "name": "Omar Nasser", "attributes": { "first_name": "Omar" } }, { "phone": "+12025550133", "name": "Lina Saleh", "attributes": { "first_name": "Lina" } } ] } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/contacts/import")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Import a list into the phonebook. Matched by number: people already there are updated, so sending it again is safe. 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.Post, "https://api.aigently.ai/v1/contacts/import") { Content = new StringContent( """ { "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "contacts": [ { "phone": "+12025550132", "name": "Omar Nasser", "attributes": { "first_name": "Omar" } }, { "phone": "+12025550133", "name": "Lina Saleh", "attributes": { "first_name": "Lina" } } ] } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "project_id" => "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "contacts" => [ [ "phone" => "+12025550132", "name" => "Omar Nasser", "attributes" => [ "first_name" => "Omar", ], ], [ "phone" => "+12025550133", "name" => "Lina Saleh", "attributes" => [ "first_name" => "Lina", ], ], ], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` Up to 1,000 people a request, matched by number, with or without its `+`: `+966501234567` and `966501234567` are one person. A number already there takes the new details, or is left as it is and counted as `skipped` when you send `update_existing: false`. A row that does not fit — not a number, not a time zone, the same number twice — is listed in `errors` by its place in `contacts`, and the rest are taken, so sending a corrected list again is how you fix one. ## Delete someone **curl** ```sh #!/bin/sh # Delete a contact. Calls already made to them stay where they are. curl -sS --fail-with-body -X DELETE "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Delete a contact. Calls already made to them stay where they are. const response = await fetch("https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d", { method: "DELETE", 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 # Delete a contact. Calls already made to them stay where they are. # pip install httpx import os import httpx response = httpx.delete( "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Delete a contact. Calls already made to them stay where they are. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("DELETE", "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d", 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 // Delete a contact. Calls already made to them stay where they are. 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/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("DELETE", 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 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 // Delete a contact. Calls already made to them stay where they are. 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.Delete, "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d") { }; 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 "DELETE", 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"; ``` They leave every group they were in. The calls already made to them stay where they are. --- # Knowledge > Keep what your agents answer from in step with your own documents. A knowledge base is what an agent answers from when a question is about your business: your files, the pages of your website, and topics written in the console. Bases are made and attached to agents in the console; through the API you keep their files up to date and have their websites read again. Reading needs `knowledge:read`. Changing needs `knowledge:write` and a **live key**: agents answer real callers from these files. A knowledge base belongs to its whole project, so a key limited to some agents cannot reach one. ## Find the base **curl** ```sh #!/bin/sh # List knowledge bases curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/knowledge-bases?project_id=0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List knowledge bases const response = await fetch("https://api.aigently.ai/v1/knowledge-bases?project_id=0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", { 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 # List knowledge bases # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/knowledge-bases", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List knowledge bases package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/knowledge-bases?project_id=0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", 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 // List knowledge bases 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/knowledge-bases?project_id=0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e")) .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 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 // List knowledge bases 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/knowledge-bases?project_id=0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e") { }; 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 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"; ``` ## Add a file **curl** ```sh #!/bin/sh # Add a file to a knowledge base. With a live key. It is indexed in the background: read it until it says indexed. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ -F "file=@opening-hours.md;type=text/markdown" ``` **JavaScript** ```js import { readFile } from "node:fs/promises"; // Add a file to a knowledge base. With a live key. It is indexed in the background: read it until it says indexed. const form = new FormData(); form.append("file", new Blob([await readFile("opening-hours.md")], { type: "text/markdown" }), "opening-hours.md"); const response = await fetch("https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, }, body: form, }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Add a file to a knowledge base. With a live key. It is indexed in the background: read it until it says indexed. # pip install httpx import os import httpx with open("opening-hours.md", "rb") as upload: response = httpx.post( "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, files={"file": ("opening-hours.md", upload, "text/markdown")}, timeout=60, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Add a file to a knowledge base. With a live key. It is indexed in the background: read it until it says indexed. package main import ( "bytes" "fmt" "io" "mime/multipart" "net/http" "os" ) func main() { var form bytes.Buffer writer := multipart.NewWriter(&form) part, _ := writer.CreateFormFile("file", "opening-hours.md") contents, err := os.ReadFile("opening-hours.md") if err != nil { panic(err) } part.Write(contents) writer.Close() request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents", &form) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", writer.FormDataContentType()) 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 // Add a file to a knowledge base. With a live key. It is indexed in the background: read it until it says indexed. import java.io.ByteArrayOutputStream; import java.nio.file.Files; import java.nio.file.Path; 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 { String boundary = Long.toHexString(System.nanoTime()); ByteArrayOutputStream form = new ByteArrayOutputStream(); form.write(("--" + boundary + "\r\nContent-Disposition: form-data; name=\"file\"; filename=\"opening-hours.md\"\r\n" + "Content-Type: text/markdown\r\n\r\n").getBytes()); form.write(Files.readAllBytes(Path.of("opening-hours.md"))); form.write(("\r\n--" + boundary + "--\r\n").getBytes()); HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "multipart/form-data; boundary=" + boundary) .method("POST", HttpRequest.BodyPublishers.ofByteArray(form.toByteArray())) .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 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 // Add a file to a knowledge base. With a live key. It is indexed in the background: read it until it says indexed. using System.Net.Http.Headers; using System.Text; var form = new MultipartFormDataContent(); var upload = new ByteArrayContent(File.ReadAllBytes("opening-hours.md")); upload.Headers.ContentType = new MediaTypeHeaderValue("text/markdown"); form.Add(upload, "file", "opening-hours.md"); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("AIGENTLY_API_KEY")); var request = new HttpRequestMessage(HttpMethod.Post, "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents") { Content = form, }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => [ "file" => new CURLFile("opening-hours.md", "text/markdown"), ], ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` Send one file as `multipart/form-data`, in a field called `file`: text, Markdown, CSV, JSON, PDF or Word, with its extension in the name. The answer is `202` with the source, `pending`. It is indexed in the background, and agents answer from it once it reads `indexed`: **curl** ```sh #!/bin/sh # Read a source's indexing status curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read a source's indexing status const response = await fetch("https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d", { 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 # Read a source's indexing status # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read a source's indexing status package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d", 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 // Read a source's indexing status 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/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d")) .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 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 // Read a source's indexing status 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/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d") { }; 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 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"; ``` | `status` | What it means | |---|---| | `pending` | Waiting for the indexer. | | `processing` | Being read now. | | `indexed` | Agents answer from it. | | `failed` | It could not be indexed, and `error` says why. | | `held` | A website page waiting for review in the console. | The same bytes twice in one base are refused with `duplicate_source`. A base holds a set number of sources; past it, a file is refused with `source_limit_reached`. ## Replace a file **curl** ```sh #!/bin/sh # Replace a file with a new version. It keeps its id; agents answer from the old version until the new one is indexed. curl -sS --fail-with-body -X PUT "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ -F "file=@opening-hours.md;type=text/markdown" ``` **JavaScript** ```js import { readFile } from "node:fs/promises"; // Replace a file with a new version. It keeps its id; agents answer from the old version until the new one is indexed. const form = new FormData(); form.append("file", new Blob([await readFile("opening-hours.md")], { type: "text/markdown" }), "opening-hours.md"); const response = await fetch("https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d", { method: "PUT", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, }, body: form, }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Replace a file with a new version. It keeps its id; agents answer from the old version until the new one is indexed. # pip install httpx import os import httpx with open("opening-hours.md", "rb") as upload: response = httpx.put( "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, files={"file": ("opening-hours.md", upload, "text/markdown")}, timeout=60, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Replace a file with a new version. It keeps its id; agents answer from the old version until the new one is indexed. package main import ( "bytes" "fmt" "io" "mime/multipart" "net/http" "os" ) func main() { var form bytes.Buffer writer := multipart.NewWriter(&form) part, _ := writer.CreateFormFile("file", "opening-hours.md") contents, err := os.ReadFile("opening-hours.md") if err != nil { panic(err) } part.Write(contents) writer.Close() request, err := http.NewRequest("PUT", "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d", &form) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", writer.FormDataContentType()) 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 // Replace a file with a new version. It keeps its id; agents answer from the old version until the new one is indexed. import java.io.ByteArrayOutputStream; import java.nio.file.Files; import java.nio.file.Path; 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 { String boundary = Long.toHexString(System.nanoTime()); ByteArrayOutputStream form = new ByteArrayOutputStream(); form.write(("--" + boundary + "\r\nContent-Disposition: form-data; name=\"file\"; filename=\"opening-hours.md\"\r\n" + "Content-Type: text/markdown\r\n\r\n").getBytes()); form.write(Files.readAllBytes(Path.of("opening-hours.md"))); form.write(("\r\n--" + boundary + "--\r\n").getBytes()); HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "multipart/form-data; boundary=" + boundary) .method("PUT", HttpRequest.BodyPublishers.ofByteArray(form.toByteArray())) .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 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 // Replace a file with a new version. It keeps its id; agents answer from the old version until the new one is indexed. using System.Net.Http.Headers; using System.Text; var form = new MultipartFormDataContent(); var upload = new ByteArrayContent(File.ReadAllBytes("opening-hours.md")); upload.Headers.ContentType = new MediaTypeHeaderValue("text/markdown"); form.Add(upload, "file", "opening-hours.md"); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("AIGENTLY_API_KEY")); var request = new HttpRequestMessage(HttpMethod.Put, "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d") { Content = form, }; 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 "PUT", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => [ "file" => new CURLFile("opening-hours.md", "text/markdown"), ], ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` A new version keeps its id and goes back to `pending`. Agents keep answering from the old version until the new one is indexed. If the new version fails, the old one stays, and `error` says what went wrong. Only a file can be replaced; a website page changes when the website is read again. ## Delete a source **curl** ```sh #!/bin/sh # Delete a source curl -sS --fail-with-body -X DELETE "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Delete a source const response = await fetch("https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d", { method: "DELETE", 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 # Delete a source # pip install httpx import os import httpx response = httpx.delete( "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Delete a source package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("DELETE", "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d", 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 // Delete a source 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/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("DELETE", 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 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 // Delete a source 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.Delete, "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d") { }; 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 "DELETE", 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"; ``` Agents stop answering from it on their next turn. ## Everything in a base **curl** ```sh #!/bin/sh # List what a knowledge base holds curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents?status=failed" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List what a knowledge base holds const response = await fetch("https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents?status=failed", { 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 # List what a knowledge base holds # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "status": "failed", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List what a knowledge base holds package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents?status=failed", 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 // List what a knowledge base holds 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/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents?status=failed")) .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 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 // List what a knowledge base holds 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/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents?status=failed") { }; 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 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"; ``` ## Read a website again Websites are given to a base in the console. Read one again when it has changed: **curl** ```sh #!/bin/sh # List the websites a knowledge base reads curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List the websites a knowledge base reads const response = await fetch("https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls", { 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 # List the websites a knowledge base reads # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List the websites a knowledge base reads package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls", 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 // List the websites a knowledge base reads 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/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls")) .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 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 // List the websites a knowledge base reads 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/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls") { }; 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 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"; ``` **curl** ```sh #!/bin/sh # Read a website again. Pages that have not changed are skipped. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls/8a0c2e4f-6b8d-4f0a-c2e4-6a8c0e2a4c6e/refresh" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read a website again. Pages that have not changed are skipped. const response = await fetch("https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls/8a0c2e4f-6b8d-4f0a-c2e4-6a8c0e2a4c6e/refresh", { method: "POST", 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 # Read a website again. Pages that have not changed are skipped. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls/8a0c2e4f-6b8d-4f0a-c2e4-6a8c0e2a4c6e/refresh", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, timeout=60, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read a website again. Pages that have not changed are skipped. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls/8a0c2e4f-6b8d-4f0a-c2e4-6a8c0e2a4c6e/refresh", 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 // Read a website again. Pages that have not changed are skipped. 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/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls/8a0c2e4f-6b8d-4f0a-c2e4-6a8c0e2a4c6e/refresh")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("POST", 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 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 // Read a website again. Pages that have not changed are skipped. 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.Post, "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls/8a0c2e4f-6b8d-4f0a-c2e4-6a8c0e2a4c6e/refresh") { }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => "", ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` Pages that have not changed are skipped, so a refresh costs only what changed. Asking while it is already being read is `crawl_running`. --- # Browser calls > Put a voice call with your agent in your own web page, and a chat beside it. The widget is one script tag, with its own look. When you want the agent inside your own product instead — your design, your buttons — your server starts the call and your page joins it with `@aigently/web`. ## Start the call on your server **curl** ```sh #!/bin/sh # Start a browser call for your page. From your server, with a live key: give the page the url and token, and it joins with @aigently/web. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/web-calls" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ -H "Idempotency-Key: visit-20931" \ --json '{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables": { "first_name": "Sara" }, "metadata": { "session": "S-20931" } }' ``` **JavaScript** ```js // Start a browser call for your page. From your server, with a live key: give the page the url and token, and it joins with @aigently/web. const response = await fetch("https://api.aigently.ai/v1/web-calls", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "visit-20931", }, body: JSON.stringify({ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables": { "first_name": "Sara" }, "metadata": { "session": "S-20931" } }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Start a browser call for your page. From your server, with a live key: give the page the url and token, and it joins with @aigently/web. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/web-calls", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", "Idempotency-Key": "visit-20931", }, json={ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables": { "first_name": "Sara", }, "metadata": { "session": "S-20931", }, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Start a browser call for your page. From your server, with a live key: give the page the url and token, and it joins with @aigently/web. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables": { "first_name": "Sara" }, "metadata": { "session": "S-20931" } }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/web-calls", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") request.Header.Set("Idempotency-Key", "visit-20931") 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 // Start a browser call for your page. From your server, with a live key: give the page the url and token, and it joins with @aigently/web. 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 { String body = """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables": { "first_name": "Sara" }, "metadata": { "session": "S-20931" } } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/web-calls")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .header("Idempotency-Key", "visit-20931") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Start a browser call for your page. From your server, with a live key: give the page the url and token, and it joins with @aigently/web. 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.Post, "https://api.aigently.ai/v1/web-calls") { Content = new StringContent( """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables": { "first_name": "Sara" }, "metadata": { "session": "S-20931" } } """, Encoding.UTF8, "application/json"), }; request.Headers.Add("Idempotency-Key", "visit-20931"); 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", "Idempotency-Key: visit-20931", ], CURLOPT_POSTFIELDS => json_encode([ "agent_id" => "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables" => [ "first_name" => "Sara", ], "metadata" => [ "session" => "S-20931", ], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` It takes what a chat takes — `agent_id`, `variables`, `metadata`, `external_id` and `language` — and the agent needs **Browser voice** among its channels, on its Configure tab. The values are set here, by your server; the page never sends any. It needs `calls:write` and a **live key**: a browser call is a real conversation, on your organization's credit. An `Idempotency-Key` makes a retry return the same call. The answer is the [conversation](/reference/objects/Conversation), `pending` until the page joins, a `url` and a `token`. The token joins this one call for 15 minutes. Give it to the page that will talk, and to nobody else — and never put an API key in a page. | Refusal | Why | |---|---| | `browser_voice_off` | Browser voice is off for this agent. | | `agent_not_published` | Publish the agent first. | | `concurrency_limit_reached` | As many browser calls are going as the agent or your organization may have. | | `daily_limit_reached` | Today's conversations on the platform's own provider keys are used up. | | `insufficient_credit` | Your organization's credit is used up. | ## Join it from the page ```ts import { joinCall } from "@aigently/web"; // Your own endpoint, which calls POST /v1/web-calls and returns url and token. const { url, token } = await (await fetch("/calls/start", { method: "POST" })).json(); const call = await joinCall( { url, token }, { onState: (state) => render(state), onTranscript: (line) => show(line), onAudioBlocked: (blocked) => playButton.toggleAttribute("hidden", !blocked), }, ); playButton.onclick = () => call.startAudio(); hangUp.onclick = () => call.end(); ``` The browser asks for the microphone when the call is joined. | `state` | What it means | |---|---| | `connecting` | Joining the call. | | `waiting` | Joined; the agent is getting ready. | | `listening` | The agent is listening. | | `thinking` | The agent is working out what to say. | | `speaking` | The agent is talking. | | `ended` | The call is over. | Each transcript line has a `speaker` — `you` or `agent` — and grows while it is spoken, then arrives once more with `final: true`. Keep the latest copy of each line by its `id`. If the browser blocks sound until the person clicks, `onAudioBlocked(true)` says so: call `startAudio()` from a click. ### With React ```tsx import { useWebCall } from "@aigently/web/react"; function Call() { const { state, transcript, start, end } = useWebCall(); const handleStart = async () => { const credentials = await (await fetch("/calls/start", { method: "POST" })).json(); await start(credentials); }; return ( <> {transcript.map((line) => (

{line.speaker}: {line.text}

))} ); } ``` The call ends by itself when the component unmounts. ## A chat on the same page ```ts import { startChat } from "@aigently/web"; const chat = await startChat({ agentId, publishableKey }); show(chat.opening); const { reply } = await chat.send("When do you open?"); ``` A chat uses the widget's own session: the agent's **publishable key** — the one in your widget snippet — from a site listed on the agent's Connect tab. Values a visitor could type go in `variables`; values your server vouches for go in a signed `identity` token, as for the [widget](/guides/widget-identity). ## Getting `@aigently/web` `@aigently/web` will be published with our other SDKs. Until then, a browser call works with any LiveKit client: join `url` with `token`, publish the microphone, and play the agent's audio. --- # AI assistants (MCP) > Let Claude, or any assistant that speaks MCP, read your conversations — and, if you allow it, act. The API is also an [MCP](https://modelcontextprotocol.io) server, at `https://api.aigently.ai/v1/mcp`. An assistant connected to it with one of your API keys can look up a conversation, read a transcript, or summarise a week of outcomes for you — using the same key, permissions and limits as your own server would. ## Connect an assistant Make a key for the assistant on the console's **API keys** page. Start with **Read only**: it reads agents, phone numbers, conversations and transcripts, and changes nothing. In Claude Code: ```sh claude mcp add --transport http aigently https://api.aigently.ai/v1/mcp \ --header "Authorization: Bearer $AIGENTLY_API_KEY" ``` Any assistant that connects to a remote MCP server over HTTP works the same way: the address above, and the key in an `Authorization: Bearer` header. For one that only runs a local program, the [command line](/cli) carries the same messages over standard input and output: ```json { "mcpServers": { "aigently": { "command": "node", "args": ["/path/to/aigently.mjs", "mcp"], "env": { "AIGENTLY_API_KEY": "ag_test_..." } } } } ``` ## What it can do Every API operation is a tool, named after it — `list_conversations`, `get_transcript`, `create_call` — and described from this reference. An assistant is shown only what its key may do: - **Reads**, for every permission the key has. - **Changes only with "Changes from AI assistants"** (`mcp:write`), and the change's own permission too. Placing a call needs `calls:write` *and* `mcp:write`: an assistant that can place calls can spend your credit. Like every write permission that reaches outside, `mcp:write` is ticked on its own, never part of a starting point. - **No uploads.** Adding a knowledge file or a picture stays with your own code. A tool the key cannot use is not listed, and cannot be called. ## Things to know - **Each tool call is an API request** under the key: it counts against the key's rate, is refused for the same reasons, and appears on the key's **Requests** page in the console. - **A test key reaches only test data.** Give an assistant a test key while you try it out. - **A tool that changes something gets its own `Idempotency-Key`** unless the assistant passes `idempotency_key`, so a repeated tool call does not place a second call. - **A refusal comes back as the tool's result**, with the error's `code` and `detail`, so the assistant can tell you what went wrong. --- # Audit log > Everything people and keys did in your organization, read by your security system. The console's **Audit log** — who made an agent, published it, made or rotated a key, changed a setting, and everything your API keys did — can be read through the API, so your security system keeps its own copy. ```sh curl https://api.aigently.ai/v1/audit-events \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` ## The key it needs Make a **live** key with **Read the audit log** (`audit:read`) that reaches **every project**. The trail is about the whole organization, so a key limited to some projects or agents is refused, and a test key reads none of it. Like every permission that reaches this far, it is ticked on its own. ## Keeping a copy Events come oldest first. Each has the action, who did it — a `person`, an `api_key`, or the `platform` itself, such as when your retention period deleted conversations — what it was done to, and the details the action recorded. `names` says what the ids in it are called today. Keep the last page's `next_cursor`, and ask again later with it for what was done since: it comes back on the last page too. An event from the last minute waits for the next read, so nothing done while you were reading lands behind your cursor. `action` narrows the list, and is repeatable. Events are kept 365 days. --- # Agents as code > Keep your agents in a repository, and deploy them the way you deploy everything else. An agent's whole definition — its prompt, configuration, voice, languages and analysis — is one document you can read, keep in a repository, change, and put back. It is the console's own export format, so a file exported from an agent's menu works here too. ## The key it needs Make a **live** key with **Change agents** (`agents:write`). It reads an agent's prompt and changes what agents say to real callers, so it is ticked on its own, never part of a starting point. A test key reads definitions and changes nothing. A key limited to some agents cannot make new ones. ## Read a definition ```sh node aigently.mjs agents retrieve-definition 8a1f3c2e-… > front-desk.json ``` `GET /v1/agents/{id}/definition` answers with `format`, the `agent` itself, and `references`: every tool, MCP server, knowledge base, calendar and callback agent it uses, **by name**. Nothing travels as an id, and nothing secret travels at all — no credential, no phone number, no domain. `GET /v1/agents/{id}/versions/{version}/definition` reads a published version the same way. ## Create one `POST /v1/agents` with a `project_id` and a `definition` makes a **draft** in that project. Each name in `references` is looked up there; what has no match is left out and listed in `unbound`, with what the agent does without it — so a definition from staging lands in production without binding to the wrong tool. Leave out `name` to use the definition's own, made free in the project; a name you give that is taken is refused with `agent_name_taken`. ## Change one ```sh node aigently.mjs agents replace-definition 8a1f3c2e-… --definition @front-desk.json ``` `PUT /v1/agents/{id}/definition` puts a definition back: the prompt, the configuration, and the tools, MCP servers and knowledge bases it names. Its kind and direction must be the agent's own. **On a published agent the change is live at once**, as an edit in the console is, and the agent shows changes not yet published until the next publish freezes them. An `agent.updated` event says when the agent's fields moved. Putting back what you read leaves the agent as it was. A model, a voice or a background your organization added itself is named in `references.voice_rows` rather than written in `voice`, and the agent keeps it while the definition still names it and leaves that `voice` field at its default. To move to another, set the field in `voice`. A recorded greeting is never in a definition, and the agent keeps it. Leave out `surfaces` and the agent keeps its own. A definition is checked as an edit in the console is: the prompt, the description and the knowledge settings have the console's limits, and `surfaces` lists each surface once. A callback agent must be an inbound agent that takes phone calls, and one your key reaches; otherwise it is listed in `unbound`. ## Publish `POST /v1/agents/{id}/publish`, with an optional `note`, runs the console's own Publish check — the prompt, tools and their credentials, models, transfer destinations, and the agent's rehearsals — and either freezes the agent as its next version or refuses with `agent_not_publishable`, every reason in `errors`. The version's history in the console names the key that published it. The tools and credentials an agent uses can be put in place the same way ([Tools and credentials](/guides/tools)), and its saved conversations rehearsed before you publish ([Evaluations in your pipeline](/guides/evaluations)). A deploy step in your pipeline is then three requests: replace the definition, publish, and pin your integrations to the version it answered with ([Pin a version](/guides/variables#pin-a-version)). ## Delete `DELETE /v1/agents/{id}` takes the agent off the air and into the trash. The console can restore it for 30 days, with its conversations and recordings; then it is gone for good. --- # Tools and credentials > Manage the APIs your agents call mid-conversation, and the credentials they send, from your own pipeline. A **tool** is a request an agent can make in the middle of a conversation: look up an order, book a table, check a balance. An **MCP server** gives an agent every tool a remote server offers. Both can send a **credential** from the vault. All three can be managed through the API, so the pipeline that deploys your agents ([Agents as code](/guides/agents-as-code)) can put their tools and credentials in place too. ## The keys they need - **Change tools** (`tools:write`) reads, makes, changes and deletes tools and MCP servers. It is ticked on its own, never part of a starting point: a tool decides where an agent sends what a caller tells it. - **Write tool credentials** (`vault:write`) adds, rotates and deletes credentials. **Only an owner can make a key with it**, because only owners manage the vault in the console. The key must reach every project, since a credential belongs to the organization and is given to projects. Both need a **live** key to change anything. A test key can read tools and MCP servers, and changes nothing. A key limited to some agents cannot change tools, because a tool belongs to its whole project. ## Add a credential ```sh node aigently.mjs vault-secrets create --name "Orders API" --secret "$ORDERS_API_TOKEN" \ --project-ids 0b1c2d3e-… ``` The answer has the credential's `id`, its name, its last four characters and the projects that may use it. **Its value is never sent back** by anything: not by this answer, the list, the console, or the audit log. Send a new `secret` with `PATCH /v1/vault/secrets/{id}` to rotate it; tools send the new value from their next request. The list shows `status: revoked` for a credential an owner revoked in the console, which cannot be changed again (`credential_revoked`). Only tool credentials are here. A model provider's key decides who bills your organization, so it stays in the console. ## Create a tool `POST /v1/tools` takes the tool's `name`, the `description` its model reads, the JSON Schema of its `parameters`, and the `http` request it makes: ```json { "method": "GET", "url": "https://orders.aigently.ai/v1/orders/{order_id}", "auth": { "type": "bearer", "vault_key_id": "2e4a6c8e-…" } } ``` The same rules as the console apply: - **The address must be public.** An address on a private network is refused with `validation_failed`. - **A credential must be a tool credential given to the tool's project.** Otherwise the request is refused with `validation_failed`. - **A credential goes only where it already goes.** The first tool that sends it decides the host it may be sent to (`bound_hosts` on the credential). An API key can use it on that host as often as you like, but can never send it anywhere new. That request is refused with `permission_denied`. An owner or an admin can send it somewhere new by saving the change in the console. So a leaked key cannot point your credential at a server of its own. Then give the tool to agents by name, in `references.tools` of their definitions. ## MCP servers `POST /v1/mcp-servers` adds a remote MCP server to a project, by `url`, with an optional `auth_key_id`, `allowed_tools` and `timeout_ms`. It follows the same address and credential rules as a tool. Give it to agents by name, in `references.mcp_servers` of their definitions. A deployment that does not run MCP servers answers `feature_disabled`. ## What reads hide, and what is kept A tool's header values and an MCP server's path and query are shown as `••••` when you read them, because they often are the credential. Keep secrets in the vault and name them, rather than in a header. **Sending a hidden value back keeps what is stored.** You can read a tool, change its description or add a header, and send the whole `http` back. Every value still reading `••••` keeps its stored value. A `••••` with nothing stored behind it, in a new tool or a new header, is refused rather than sent to your API as a credential. ## Changes reach agents at once A changed or deleted tool, server or credential reaches every agent that has it on its next turn. `agent_count` on a tool says how many agents that is. Each change is in the [audit log](/guides/audit-log) under the key that made it, with the console's own event names. --- # Evaluations in your pipeline > Rehearse an agent's saved conversations on every change, and fail the build when one no longer passes. An **evaluation** is a short conversation written down: what a caller says, and what must be true of the agent's replies. The console calls them saved conversations, and publishing already rehearses every one and refuses while one fails. Through the API, your build pipeline can rehearse them too — on a pull request, before a deploy, or every night — and stop when the agent no longer does what it used to. ## The key it needs **Run evaluations** (`evaluations:run`) rehearses an agent's evaluations and reads the results. It is ticked on its own, because every run is real model calls, charged to your credit under Testing. A test key can hold it: rehearsing changes nothing real. Adding and deleting evaluations changes what publishing lets through, so it takes **Change agents** (`agents:write`) and a **live** key, as other changes to an agent do. ## In a build step ```sh curl -O https://developers.aigently.ai/aigently.mjs node aigently.mjs evaluate 8a1f3c2e-… ``` `evaluate` starts a run, waits for it, prints each conversation's outcome with the reason for every expectation it missed, and exits: | Exit code | Means | |---|---| | `0` | Every evaluation passed. | | `1` | At least one failed, or the request was refused. | | `3` | None failed, but some could not be checked. | A conversation that could not be checked says nothing about the agent: the provider had a bad minute, the run ran out of time, or the credit was used up. Treat `3` as a pass or a failure, whichever your pipeline needs. For example, in GitHub Actions: ```yaml - name: Rehearse the front desk run: | curl -sO https://developers.aigently.ai/aigently.mjs node aigently.mjs evaluate 8a1f3c2e-… env: AIGENTLY_API_KEY: ${{ secrets.AIGENTLY_API_KEY }} ``` ## Through the API `POST /v1/agents/{id}/evaluation-runs` answers at once with a run whose `status` is `queued`. Read it with `GET /v1/evaluation-runs/{id}` every few seconds until `status` is `finished`; then `passed`, `failed` and `not_checked` count the outcomes, and `results` has every conversation's `outcome`, its `verdicts` — one per expectation, each with the judge's `why` — and the rehearsal's `transcript`. - **One run at a time in an organization**, from the console or the API. Asking while one is going is refused with `evaluation_run_in_progress`. Wait for that run to finish, then ask again. - **The agent as it is now** is rehearsed, published or not: replace a draft's definition, rehearse it, and publish only if it passes ([Agents as code](/guides/agents-as-code)). - **A run is kept for 30 days.** Each conversation's latest result also shows in the console's editor, as one from the Rehearse all button does. ## Keep them in your repository `GET /v1/agents/{id}/evaluations` lists them, each with its latest result. `POST /v1/agents/{id}/evaluations` adds one — a `name`, the caller's `turns` and the `expectations` — and `DELETE` removes one. An agent keeps at most 50; past that, adding one is refused with `evaluation_limit_reached`. --- # Terraform > Keep agents, their tools and credentials, their evaluations and your webhook receivers in Terraform. The Terraform provider manages what [Agents as code](/guides/agents-as-code), [Tools and credentials](/guides/tools) and [Evaluations in your pipeline](/guides/evaluations) do through the API, so one `terraform apply` can put a customer's whole setup in place and the next one shows what changed in the console since. | Resource | What it is | |---|---| | `aigently_agent` | An agent, kept as its definition, and published if you ask | | `aigently_tool` | A request an agent can make mid-conversation | | `aigently_mcp_server` | A remote MCP server whose tools agents can be given | | `aigently_vault_secret` | A tool credential, written and never read back | | `aigently_evaluation` | A conversation an agent has to keep handling | | `aigently_webhook_endpoint` | A receiver for a project's events ([Webhooks](/guides/webhooks)) | Two data sources read what you do not manage: `aigently_project`, found by its name, and `aigently_agent`, by its id. ## Getting it The provider will be published to the Terraform Registry, as `aigently/aigently`, with our other SDKs. Until then, every resource here is a request you can make yourself, and the guides linked above show each one. ## The key it needs A **live** key ([Keys](/guides/keys)), in `AIGENTLY_API_KEY` or the provider's `api_key`, holding what your configuration uses: `agents:read` and `agents:write` for agents, `tools:write` for tools and MCP servers, `vault:write` for credentials — which only an owner can give a key — `evaluations:run` with `agents:write` for evaluations, and `webhooks:read` and `webhooks:write` for receivers. ## A configuration ```hcl terraform { required_providers { aigently = { source = "aigently/aigently" } } } provider "aigently" {} variable "orders_api_token" { type = string sensitive = true } data "aigently_project" "front" { name = "Front desk" } resource "aigently_vault_secret" "orders" { name = "Orders API" secret_wo = var.orders_api_token secret_wo_version = 1 project_ids = [data.aigently_project.front.id] } resource "aigently_tool" "lookup_order" { project_id = data.aigently_project.front.id name = "lookup_order" description = "Look up the status of an order by its number." parameters = jsonencode({ type = "object", properties = { order_id = { type = "string" } } }) http = jsonencode({ method = "GET" url = "https://orders.aigently.ai/v1/orders/{order_id}" auth = { type = "bearer", vault_key_id = aigently_vault_secret.orders.id } }) } resource "aigently_agent" "front_desk" { project_id = data.aigently_project.front.id definition = jsonencode(merge( jsondecode(file("front-desk.json")), { references = { tools = [aigently_tool.lookup_order.name] } }, )) publish = true } ``` `front-desk.json` is the file the console exports from the agent's menu, or what `GET /v1/agents/{id}/definition` answers. ## How a change shows in a plan - **A definition is compared for what it says.** The API fills in every default a definition leaves out, and none of those is a change. A value edited in the console is: the plan shows that one value going back to what you wrote. - **Name a tool through its resource**, as above, so Terraform makes the tool before the agent. A definition that names something the project does not have is applied without it, with a warning, and the plan keeps showing it until the project has it. - **A definition for another kind or direction of agent makes a new agent**, because an agent keeps both for its whole life. - **Header values and an MCP server's address are hidden when they are read**, and the provider keeps what you configured rather than the hidden form, so they show no change. ## Publishing With `publish = true`, every change is published through the console's own Publish check, and `published_version` is the version it made — what [Pin a version](/guides/variables#pin-a-version) pins a conversation to. A refused publish fails the apply with every reason. On an existing agent, the next apply publishes again; a new agent stays made, and Terraform marks it tainted, so run `terraform untaint` once the reasons are fixed to keep it. ## Credentials `secret_wo` sends a credential's value without Terraform ever keeping it, and sends it again when you raise `secret_wo_version`. It needs Terraform 1.11 or later. `secret` works with any version, and Terraform keeps it in its state, as it does every sensitive value. Either way, a value replaced in the console is noticed from its last four characters, and the next apply puts yours back. ## Importing Each resource imports by its id: `terraform import aigently_agent.front_desk 8a1f3c2e-…`. An evaluation imports as `/`. Values a read hides — a tool's headers, a credential, a receiver's signing secret — are not imported. The first plan after an import shows a tool's hidden values being set, and a receiver's secret stays empty until it is made again. --- # Mobile apps > Put a voice call with your agent, and a chat beside it, in your own iOS or Android app. The mobile SDKs do in an app what `@aigently/web` does in a page ([Browser calls](/guides/browser-calls)): your server starts a call and your app joins it, and a chat runs on the agent's own widget session. The calls, the states and the rules are the same. ## Start the call on your server **curl** ```sh #!/bin/sh # Start a browser call for your page. From your server, with a live key: give the page the url and token, and it joins with @aigently/web. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/web-calls" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ -H "Idempotency-Key: visit-20931" \ --json '{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables": { "first_name": "Sara" }, "metadata": { "session": "S-20931" } }' ``` **JavaScript** ```js // Start a browser call for your page. From your server, with a live key: give the page the url and token, and it joins with @aigently/web. const response = await fetch("https://api.aigently.ai/v1/web-calls", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "visit-20931", }, body: JSON.stringify({ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables": { "first_name": "Sara" }, "metadata": { "session": "S-20931" } }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Start a browser call for your page. From your server, with a live key: give the page the url and token, and it joins with @aigently/web. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/web-calls", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", "Idempotency-Key": "visit-20931", }, json={ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables": { "first_name": "Sara", }, "metadata": { "session": "S-20931", }, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Start a browser call for your page. From your server, with a live key: give the page the url and token, and it joins with @aigently/web. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables": { "first_name": "Sara" }, "metadata": { "session": "S-20931" } }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/web-calls", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") request.Header.Set("Idempotency-Key", "visit-20931") 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 // Start a browser call for your page. From your server, with a live key: give the page the url and token, and it joins with @aigently/web. 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 { String body = """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables": { "first_name": "Sara" }, "metadata": { "session": "S-20931" } } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/web-calls")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .header("Idempotency-Key", "visit-20931") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Start a browser call for your page. From your server, with a live key: give the page the url and token, and it joins with @aigently/web. 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.Post, "https://api.aigently.ai/v1/web-calls") { Content = new StringContent( """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables": { "first_name": "Sara" }, "metadata": { "session": "S-20931" } } """, Encoding.UTF8, "application/json"), }; request.Headers.Add("Idempotency-Key", "visit-20931"); 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", "Idempotency-Key: visit-20931", ], CURLOPT_POSTFIELDS => json_encode([ "agent_id" => "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables" => [ "first_name" => "Sara", ], "metadata" => [ "session" => "S-20931", ], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` This is the same request as for a browser call. It needs `calls:write` and a **live key**, which stays on your server: never put an API key in an app. The answer's `url` and `token` go to the app, and the token joins this one call for 15 minutes. ## Join it from an iOS app ```swift import Aigently // Your own endpoint, which calls POST /v1/web-calls and returns url and token. let credentials = try await yourServer.startCall() let call = try await joinCall(credentials, handlers: CallHandlers( onState: { state in print(state) }, onTranscript: { line in print(line.speaker, line.text) } )) ``` It needs iOS 13 or macOS 10.15, and Xcode 16.3 or later. Add `NSMicrophoneUsageDescription` to your Info.plist: the first call asks for the microphone, and a person who refuses gets a call that ends at once. For SwiftUI, `WebCallModel` holds a call as state and hangs up when it goes away. ## Join it from an Android app ```kotlin import ai.aigently.* // Your own endpoint, which calls POST /v1/web-calls and returns url and token. val credentials = yourServer.startCall() val call = joinCall(context, credentials, CallHandlers( onState = { state -> render(state) }, onTranscript = { line -> show(line) }, )) ``` It needs Android 5.0 (API 21) or later. Ask for `RECORD_AUDIO` before you join: a library cannot show the permission prompt, and a call joined without it ends at once. For Compose, `WebCallController` holds a call as state. ## What the call tells you | State | What it means | |---|---| | connecting | Joining the call. | | waiting | Joined; the agent is getting ready. | | listening | The agent is listening. | | thinking | The agent is working out what to say. | | speaking | The agent is talking. | | ended | The call is over. | Each transcript line has a speaker, you or the agent, and grows while it is spoken, then arrives once more as final. Keep the latest copy of each line by its id: `Transcript` does this on both platforms. The agent's audio plays by itself. ## A chat ```swift let chat = try await startChat(ChatOptions( agentId: "8a1f3c2e-…", publishableKey: "pk_…", origin: "https://www.aigently.ai" )) let answer = try await chat.send("When do you open?") ``` ```kotlin val chat = startChat(ChatOptions( agentId = "8a1f3c2e-…", publishableKey = "pk_…", origin = "https://www.aigently.ai", )) val answer = chat.send("When do you open?") ``` A chat uses the agent's **publishable key**, the one in your widget snippet. **An app names the site it speaks for**: the platform opens a chat only for a domain listed under **Allow your domains** on the agent's Connect tab, and it reads that domain from the request's `Origin` header, which a browser sends and an app does not. Pass one of the listed domains, usually your own website's, as `origin`. Values a person could type go in `variables`, as text. Values your server vouches for go in a signed `identity` token, as for the [widget](/guides/widget-identity). ## Getting the SDKs The mobile SDKs will be published with our other SDKs. Until then, a call works with any LiveKit client: join `url` with `token`, publish the microphone, and play the agent's audio. --- # Live calls > Follow a call's transcript while it happens, and have the agent say something, take a note, or transfer the caller. While a call is happening, your system can read what is being said, and ask the call to do three things: say a sentence, take a note, or put the caller through to a person. ## Follow the transcript ```sh node aigently.mjs follow 5f0c9a52-… ``` `GET /v1/conversations/{id}/live?after=0&wait=20` answers as soon as there is a line after `after`, or after `wait` seconds with none. Each line has its `seq`, its `role` (`user` for the caller, `assistant` for the agent), its `text` and when it was said. Send `next_after` back as `after` and ask again, until `ended` is true: then the call is over and you have every line. - It needs **Read transcripts** (`transcripts:read`), as reading the finished transcript does. - Phone calls and browser calls have a live transcript. A chat does not: read its messages from its transcript. - Lines are kept for a day. The conversation's transcript is the record after that. ## Ask the call to do something Each request needs **Control live calls** (`calls:control`), a permission that is never part of a starting point: it changes what a caller hears while they hear it. Each answers `202` at once with a command. The call carries it out within a second or so, and `GET /v1/conversations/{id}/commands/{command_id}` says how it went: `sent`, `taken`, then `done` or `failed`. - **Say** — `POST /v1/conversations/{id}/say` with `text`. The agent says it word for word, in its own voice, once it has finished what it is saying. It is in the transcript like anything else the agent says. - **Note** — `POST /v1/conversations/{id}/notes` with `text`: something your system knows that the caller did not say, such as a payment that went through. The caller does not hear it. It reaches the agent as information, never as instructions, so it cannot change what the agent is for. With `respond: true`, the agent answers it at once; otherwise it uses it on its next turn. - **Transfer** — `POST /v1/conversations/{id}/transfer` with `to_number`, or without it for the agent's own transfer number. The agent says its transfer line, the number rings, and the agent leaves once somebody answers, or tells the caller nobody could. The number is checked like any number an agent calls. A call is transferred once, and only a phone call can be. A call takes these only once it has been answered and before it ends; otherwise the request is refused with `conversation_not_answered` or `conversation_ended`. Every command is in the [audit log](/guides/audit-log) under the key that sent it. ## With a test key A test call is played rather than rung, and the same requests work on it: its lines appear in the live transcript as its script plays, and a command is carried out at once. A sentence to say appears as the agent's next line; nothing rings. See [Test mode](/guides/test-mode). --- # WhatsApp conversations > Start a WhatsApp conversation with an approved template, and let your agent take it from the first reply. Your agents already answer people who write to your WhatsApp numbers. With the API, your system can write first: an appointment reminder, a delivery notice, a renewal. WhatsApp allows a business to start a conversation only with a **message template** Meta has approved, so that is what you send. When the person writes back, the number's agent answers, in the same conversation. ## The key it needs **Start WhatsApp conversations** (`whatsapp:write`), a permission that is never part of a starting point: it puts a message on a real person's phone. Starting a conversation needs a **live** key. A test key can list your numbers and templates, and sends nothing, because there are no WhatsApp test numbers. ## Find your number and its templates ```sh node aigently.mjs whatsapp list-senders node aigently.mjs whatsapp list-templates 7d9f1b3d-… ``` `GET /v1/whatsapp/senders` lists your WhatsApp numbers and the agent that answers each. `GET /v1/whatsapp/senders/{id}/templates` lists the templates Meta has approved for that number's business account, each with its `body` and how many `parameters` it takes. Write and approve templates in Meta's WhatsApp Manager; the list here follows within a few minutes. It needs the connection's WhatsApp Business account id and an access token: without them, the request is refused with `whatsapp_not_ready`. ## Start the conversation `POST /v1/whatsapp/conversations`, with an `Idempotency-Key`: ```json { "sender_id": "7d9f1b3d-…", "to_number": "+966501234567", "template": { "name": "appointment_reminder", "language": "en_US", "parameters": ["Sara", "Monday at 10"] }, "variables": { "first_name": "Sara" }, "metadata": { "booking": "4471" } } ``` - **The template is checked first.** A name or language Meta has not approved, or the wrong number of `parameters`, is refused with `validation_failed`, naming the field. Nothing is sent. - **The answer is the conversation**, `channel: whatsapp` and `direction: outbound`. Its first line is the template's own words, so when the person writes back, the agent knows what it said. Your `variables` fill the agent's placeholders, as they do for a call. - **It waits a day for an answer**, which is WhatsApp's own window for one. After a reply, it closes after the agent's usual quiet period. If nobody answers within a day, it ends. - **Sent once.** The same `Idempotency-Key` again answers with the first conversation and sends nothing. - **Meta can still refuse a message**, for example to a number that is not on WhatsApp. The conversation then ends `failed`, with Meta's reason in `error`. A refusal worth retrying, such as a rate limit, is retried by the platform. Each retry checks again first: if the project has been frozen, the credit used up or the number listed in the meantime, or the retries run out, the template is not sent and the conversation ends `failed` with the reason in `error`. - **Not to anyone on a block list.** A number on your organization's do-not-call list or WhatsApp block list is refused with `do_not_call`. Each conversation's events reach your webhook receivers as any conversation's do ([Webhooks](/guides/webhooks)). --- # Glossary > The words the API uses, and what each means. | Word | Meaning | |---|---| | **Conversation** | One exchange on any channel — the main object in the API. The console calls these *Calls*. | | **Call** | A conversation on the phone (`channel: "phone"`). `POST /v1/calls` places one. | | **Chat** | A text conversation. `POST /v1/chats` starts one. | | **Browser voice** | A voice conversation in a web page. Its channel is `voice`; the agent's setting calls it *Browser voice*. | | **Variable** | A value that fills a `{{placeholder}}` in an agent's instructions or first message. The console calls them *fields*. See [Variables](/guides/variables). | | **Metadata** | Your own data on a conversation. The agent never sees it; you get it back everywhere. | | **Context lookup** | Your server, asked who is calling as an inbound call is answered. See [Inbound calls](/guides/inbound-calls). | | **Webhook** | A message the platform sends your server when something happens. See [Webhooks](/guides/webhooks). | | **`status`** | Where a conversation stands: `pending`, `active`, `completed` or `failed`. | | **`disposition`** | How a phone call ended on the phone network: answered, busy, no answer and so on. | | **`ended_by`** | What ended it: `caller`, `agent`, `operator` (a person in the console), `api`, `transfer` (handed to a person), `system` (a time limit) or `failure`. Null where nothing was ended — a call nobody answered. | | **`revision`** | A number on every conversation that only goes up. Of two copies, keep the higher. | | **`finished`** (on a chat turn) | The agent has nothing more to ask. The chat stays open until it is ended. | | **`mode` and `livemode`** | `mode` is `live`, `test` (the console's own test calls) or `sandbox` (a test key's). `livemode` is false only for `sandbox`. | | **Test key** | An `ag_test_…` key. Its calls ring nobody and its data stays apart. See [Test mode](/guides/test-mode). | | **Idempotency key** | Your own id for a request, so sending it again never does it twice. See [Safe retries](/guides/idempotency). | | **Cursor** | A bookmark for where the next page of a list starts. | | **Problem document** | How every error is sent: a JSON object with a stable `code`. See [Errors](/errors). | --- # Changelog > What changed in the API, and the rules for what may change. ## What may change, and what may not - **Additions ship at any time** without a new version: new endpoints, new optional request fields, new fields in an answer, new values in a field like `status`, and new event types. Read the fields you know and ignore the rest, and treat a value you do not recognise as "something else". - **Anything that would break a working integration goes into `/v2`.** `/v1` keeps working. - **A planned removal is announced** here, and the responses it affects carry `Deprecation` and `Sunset` headers before anything is removed. ## October 2026 — `/v1` The first release of the API. - **Calls**: place a call with an outbound agent, with its variables and your metadata, safely retried with an `Idempotency-Key`; end a call, or cancel one still ringing; name the hours a call may start in. - **Scheduled calls**: ask for a call later, placed at its time or at the next opening of its calling hours, and cancel it before then. - **Campaigns**: call a list of people at a pace you set, in calling hours read in each person's own time zone; start, pause, resume and cancel it; read how each person's calls went; and hear each step as an event. - **Contacts**: keep each project's phonebook in step — add, change, find by number, delete, and import up to 1,000 people a request. An inbound agent can fill its fields from the caller's entry. - **Knowledge**: add, replace and delete the files your agents answer from, follow their indexing, and have a website read again. - **Browser calls**: start a voice call with an agent from your server and join it from your own page, with `@aigently/web`. - **Chats**: start and continue a chat with any agent, one message at a time, as a whole reply or streamed; send pictures. - **Conversations**: list, read and sync them, with transcripts, analyses and five-minute recording links; find them by what was said or by your own `external_id`; read what each cost; run the analysis again; delete them, and list the ones deleted. - **Inbound calls**: the context lookup asks your server who is calling while the phone is answered. - **Webhooks**: an event for each change in a conversation's life, signed the Standard Webhooks way, with live and test receivers. Manage receivers through the API, and rotate a secret with an overlap so no event is refused while you update. - **Events**: every event your receivers were sent, kept for 30 days, to recover what one missed. - **Billing**: the credit balance and every movement of credit. - **Phone numbers**: list them, and point one at an agent with a live key. - **Do not call**: one list per organization that no agent rings, kept from your own systems. - **Keys**: limit a key to your servers' addresses. A key pushed to a public repository on GitHub is revoked, once our place in GitHub's secret scanning program is confirmed. - **Test mode**: test keys, test numbers that ring nobody, test calls to your own agents, and `aigently listen` for your laptop. - **AI assistants**: the API as an MCP server, read-only unless a key allows changes. - **Audit log**: everything people and keys did in your organization, for your security system. - **Versions**: list the versions an agent was published as, and pin a conversation to one. - **Agents as code**: read, create, replace, publish and delete agents from their definitions. - **Tools and credentials**: make, change and delete tools and MCP servers, and add tool credentials to the vault, where no answer ever carries one back. - **Evaluations**: rehearse an agent's saved conversations from your build pipeline and read how each did; `aigently evaluate` fails the build step when one no longer passes. - **Live calls**: follow a call's transcript while it happens, and have the agent say a sentence, take a note from your systems, or transfer the caller to a person. - **Mobile apps**: iOS and Android SDKs that join a call your server started and run a chat, as `@aigently/web` does in a page. - **Terraform**: keep agents, tools, credentials, evaluations and webhook receivers in Terraform. - **WhatsApp**: start a WhatsApp conversation with an approved template, and the number's agent answers when the person writes back. - **The command line**: every operation as a command, and an agent's fields written as TypeScript or Python types. - **Examples** in seven languages for every operation, run against the platform before publishing. --- # API reference > Every operation of the Aigently API. Every operation, by what it is about. Each page lists its parameters, its body, its answer and its errors, with an example in seven languages and a *Try it* that takes a test key. Requests go to `https://api.aigently.ai`, with an API key in `Authorization: Bearer `. The whole description is [the OpenAPI file](/openapi.v1.json). ## Keys | Operation | Request | |---|---| | [Describe this API key](/reference/getMe) | `GET /v1/me` | ## Projects | Operation | Request | |---|---| | [List projects](/reference/listProjects) | `GET /v1/projects` | ## Agents | Operation | Request | |---|---| | [List agents](/reference/listAgents) | `GET /v1/agents` | | [Create an agent](/reference/createAgent) | `POST /v1/agents` | | [Get an agent](/reference/getAgent) | `GET /v1/agents/{agent_id}` | | [Delete an agent](/reference/deleteAgent) | `DELETE /v1/agents/{agent_id}` | | [Get an agent's definition](/reference/getAgentDefinition) | `GET /v1/agents/{agent_id}/definition` | | [Replace an agent's definition](/reference/replaceAgentDefinition) | `PUT /v1/agents/{agent_id}/definition` | | [Publish an agent](/reference/publishAgent) | `POST /v1/agents/{agent_id}/publish` | | [List an agent's versions](/reference/listAgentVersions) | `GET /v1/agents/{agent_id}/versions` | | [Get a published version's definition](/reference/getAgentVersionDefinition) | `GET /v1/agents/{agent_id}/versions/{version}/definition` | ## Evaluations | Operation | Request | |---|---| | [Run an agent's evaluations](/reference/runEvaluations) | `POST /v1/agents/{agent_id}/evaluation-runs` | | [List an agent's evaluations](/reference/listEvaluations) | `GET /v1/agents/{agent_id}/evaluations` | | [Add an evaluation](/reference/createEvaluation) | `POST /v1/agents/{agent_id}/evaluations` | | [Delete an evaluation](/reference/deleteEvaluation) | `DELETE /v1/agents/{agent_id}/evaluations/{evaluation_id}` | | [Get an evaluation run](/reference/getEvaluationRun) | `GET /v1/evaluation-runs/{run_id}` | ## Phone numbers | Operation | Request | |---|---| | [List phone numbers](/reference/listPhoneNumbers) | `GET /v1/phone-numbers` | | [Point a phone number at an agent](/reference/updatePhoneNumber) | `PATCH /v1/phone-numbers/{phone_number_id}` | ## Calls | Operation | Request | |---|---| | [Place a call](/reference/createCall) | `POST /v1/calls` | | [End a conversation](/reference/endConversation) | `POST /v1/conversations/{conversation_id}/end` | ## Scheduled calls | Operation | Request | |---|---| | [List scheduled calls](/reference/listScheduledCalls) | `GET /v1/scheduled-calls` | | [Schedule a call](/reference/createScheduledCall) | `POST /v1/scheduled-calls` | | [Get a scheduled call](/reference/getScheduledCall) | `GET /v1/scheduled-calls/{scheduled_call_id}` | | [Cancel a scheduled call](/reference/cancelScheduledCall) | `DELETE /v1/scheduled-calls/{scheduled_call_id}` | ## Campaigns | Operation | Request | |---|---| | [List campaigns](/reference/listCampaigns) | `GET /v1/campaigns` | | [Create a campaign](/reference/createCampaign) | `POST /v1/campaigns` | | [Get a campaign](/reference/getCampaign) | `GET /v1/campaigns/{campaign_id}` | | [Cancel a campaign](/reference/cancelCampaign) | `POST /v1/campaigns/{campaign_id}/cancel` | | [List a campaign's contacts](/reference/listCampaignContacts) | `GET /v1/campaigns/{campaign_id}/contacts` | | [Add contacts to a campaign](/reference/addCampaignContacts) | `POST /v1/campaigns/{campaign_id}/contacts` | | [Pause a campaign](/reference/pauseCampaign) | `POST /v1/campaigns/{campaign_id}/pause` | | [Resume a campaign](/reference/resumeCampaign) | `POST /v1/campaigns/{campaign_id}/resume` | | [Start a campaign](/reference/startCampaign) | `POST /v1/campaigns/{campaign_id}/start` | ## Contacts | Operation | Request | |---|---| | [List contacts](/reference/listContacts) | `GET /v1/contacts` | | [Add a contact](/reference/createContact) | `POST /v1/contacts` | | [Import contacts](/reference/importContacts) | `POST /v1/contacts/import` | | [Get a contact](/reference/getContact) | `GET /v1/contacts/{contact_id}` | | [Change a contact](/reference/updateContact) | `PATCH /v1/contacts/{contact_id}` | | [Delete a contact](/reference/deleteContact) | `DELETE /v1/contacts/{contact_id}` | ## Knowledge | Operation | Request | |---|---| | [List knowledge bases](/reference/listKnowledgeBases) | `GET /v1/knowledge-bases` | | [List the websites a knowledge base reads](/reference/listKnowledgeCrawls) | `GET /v1/knowledge-bases/{knowledge_base_id}/crawls` | | [Read a website again](/reference/refreshKnowledgeCrawl) | `POST /v1/knowledge-bases/{knowledge_base_id}/crawls/{crawl_id}/refresh` | | [List a knowledge base's sources](/reference/listKnowledgeDocuments) | `GET /v1/knowledge-bases/{knowledge_base_id}/documents` | | [Add a file to a knowledge base](/reference/uploadKnowledgeDocument) | `POST /v1/knowledge-bases/{knowledge_base_id}/documents` | | [Get a source](/reference/getKnowledgeDocument) | `GET /v1/knowledge-bases/{knowledge_base_id}/documents/{document_id}` | | [Replace a file](/reference/replaceKnowledgeDocument) | `PUT /v1/knowledge-bases/{knowledge_base_id}/documents/{document_id}` | | [Delete a source](/reference/deleteKnowledgeDocument) | `DELETE /v1/knowledge-bases/{knowledge_base_id}/documents/{document_id}` | ## Tools | Operation | Request | |---|---| | [List MCP servers](/reference/listMcpServers) | `GET /v1/mcp-servers` | | [Add an MCP server](/reference/createMcpServer) | `POST /v1/mcp-servers` | | [Get an MCP server](/reference/getMcpServer) | `GET /v1/mcp-servers/{server_id}` | | [Change an MCP server](/reference/updateMcpServer) | `PATCH /v1/mcp-servers/{server_id}` | | [Delete an MCP server](/reference/deleteMcpServer) | `DELETE /v1/mcp-servers/{server_id}` | | [List tools](/reference/listTools) | `GET /v1/tools` | | [Create a tool](/reference/createTool) | `POST /v1/tools` | | [Get a tool](/reference/getTool) | `GET /v1/tools/{tool_id}` | | [Change a tool](/reference/updateTool) | `PATCH /v1/tools/{tool_id}` | | [Delete a tool](/reference/deleteTool) | `DELETE /v1/tools/{tool_id}` | ## Vault | Operation | Request | |---|---| | [List tool credentials](/reference/listVaultSecrets) | `GET /v1/vault/secrets` | | [Add a tool credential](/reference/createVaultSecret) | `POST /v1/vault/secrets` | | [Get a tool credential](/reference/getVaultSecret) | `GET /v1/vault/secrets/{secret_id}` | | [Change a tool credential](/reference/updateVaultSecret) | `PATCH /v1/vault/secrets/{secret_id}` | | [Delete a tool credential](/reference/deleteVaultSecret) | `DELETE /v1/vault/secrets/{secret_id}` | ## Do not call | Operation | Request | |---|---| | [List the do-not-call list](/reference/listDoNotCall) | `GET /v1/do-not-call` | | [Add a number to the do-not-call list](/reference/addDoNotCall) | `POST /v1/do-not-call` | | [Take a number off the do-not-call list](/reference/removeDoNotCall) | `DELETE /v1/do-not-call/{number}` | ## Chats | Operation | Request | |---|---| | [Upload a picture](/reference/uploadAttachment) | `POST /v1/attachments` | | [Start a chat](/reference/createChat) | `POST /v1/chats` | | [Send a message](/reference/sendMessage) | `POST /v1/conversations/{conversation_id}/messages` | ## WhatsApp | Operation | Request | |---|---| | [Start a WhatsApp conversation](/reference/startWhatsappConversation) | `POST /v1/whatsapp/conversations` | | [List WhatsApp numbers](/reference/listWhatsappSenders) | `GET /v1/whatsapp/senders` | | [List a WhatsApp number's templates](/reference/listWhatsappTemplates) | `GET /v1/whatsapp/senders/{sender_id}/templates` | ## Web calls | Operation | Request | |---|---| | [Start a browser call](/reference/createWebCall) | `POST /v1/web-calls` | ## Conversations | Operation | Request | |---|---| | [List conversations](/reference/listConversations) | `GET /v1/conversations` | | [List deleted conversations](/reference/listDeletedConversations) | `GET /v1/conversations/deleted` | | [Get a conversation](/reference/getConversation) | `GET /v1/conversations/{conversation_id}` | | [Delete a conversation](/reference/deleteConversation) | `DELETE /v1/conversations/{conversation_id}` | | [Analyse a conversation again](/reference/analyzeConversation) | `POST /v1/conversations/{conversation_id}/analysis` | | [Get a link to a conversation's recording](/reference/getRecording) | `GET /v1/conversations/{conversation_id}/recording` | | [Get a conversation's transcript](/reference/getTranscript) | `GET /v1/conversations/{conversation_id}/transcript` | ## Live calls | Operation | Request | |---|---| | [Get a command](/reference/getConversationCommand) | `GET /v1/conversations/{conversation_id}/commands/{command_id}` | | [Follow a call's transcript live](/reference/getLiveTranscript) | `GET /v1/conversations/{conversation_id}/live` | | [Give the agent a note](/reference/addConversationNote) | `POST /v1/conversations/{conversation_id}/notes` | | [Have the agent say something](/reference/sayInConversation) | `POST /v1/conversations/{conversation_id}/say` | | [Transfer a call](/reference/transferConversation) | `POST /v1/conversations/{conversation_id}/transfer` | ## Events | Operation | Request | |---|---| | [List events](/reference/listEvents) | `GET /v1/events` | ## Webhooks | Operation | Request | |---|---| | [List webhook receivers](/reference/listWebhookReceivers) | `GET /v1/webhooks` | | [Create a webhook receiver](/reference/createWebhookReceiver) | `POST /v1/webhooks` | | [Get a webhook receiver](/reference/getWebhookReceiver) | `GET /v1/webhooks/{receiver_id}` | | [Change a webhook receiver](/reference/updateWebhookReceiver) | `PATCH /v1/webhooks/{receiver_id}` | | [Delete a webhook receiver](/reference/deleteWebhookReceiver) | `DELETE /v1/webhooks/{receiver_id}` | | [List a receiver's deliveries](/reference/listWebhookDeliveries) | `GET /v1/webhooks/{receiver_id}/deliveries` | | [Send a delivery again](/reference/resendWebhookDelivery) | `POST /v1/webhooks/{receiver_id}/deliveries/{delivery_id}/resend` | | [Change a webhook receiver's secret](/reference/rotateWebhookSecret) | `POST /v1/webhooks/{receiver_id}/rotate-secret` | | [Send a test event](/reference/testWebhookReceiver) | `POST /v1/webhooks/{receiver_id}/test` | ## Billing | Operation | Request | |---|---| | [Get the credit balance](/reference/getCreditBalance) | `GET /v1/billing/balance` | | [List credit transactions](/reference/listCreditTransactions) | `GET /v1/billing/transactions` | ## Audit log | Operation | Request | |---|---| | [List audit events](/reference/listAuditEvents) | `GET /v1/audit-events` | ## Test mode | Operation | Request | |---|---| | [Make a test call to an agent](/reference/createTestInboundCall) | `POST /v1/test/inbound-calls` | The objects these answer with are listed under [Objects](/reference/objects). --- # Describe this API key > GET /v1/me The key's name, mode, permissions and reach; its organization; what this deployment supports; and every limit that applies to it, with how many calls are in progress now. Any working key may call it. ## Answer `200` with [Me](/reference/objects/Me). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **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 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 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"; ``` --- # List projects > GET /v1/projects The projects this key can reach, oldest first. Needs `agents:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [ProjectList](/reference/objects/ProjectList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # List projects curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/projects" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List projects const response = await fetch("https://api.aigently.ai/v1/projects", { 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 # List projects # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/projects", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List projects package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/projects", 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 // List projects 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/projects")) .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 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 // List projects 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/projects") { }; 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 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"; ``` --- # List agents > GET /v1/agents The agents this key can reach, oldest first. Needs `agents:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `project_id` | query | string (uuid) or null | No | Only this project's. | | `status` | query | [AgentStatus](/reference/objects/AgentStatus) or null | No | Only these. | | `direction` | query | [AgentDirection](/reference/objects/AgentDirection) or null | No | Only these. | | `kind` | query | [AgentKind](/reference/objects/AgentKind) or null | No | Only these. | | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [AgentList](/reference/objects/AgentList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # List agents curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/agents?limit=20" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List agents const response = await fetch("https://api.aigently.ai/v1/agents?limit=20", { 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 # List agents # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/agents", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "limit": 20, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List agents package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/agents?limit=20", 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 // List agents 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/agents?limit=20")) .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 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 // List agents 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/agents?limit=20") { }; 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 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"; ``` --- # Create an agent > POST /v1/agents Make an agent in a project from a definition. It is a draft until it is published. Everything the definition names is looked up in the project by name, and what is not there is listed in `unbound` with what the agent does without it. Needs `agents:write` and a live key. ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `definition` | object | Yes | An agent definition, as `GET /v1/agents/{id}/definition` answers with or the console exports. | | `name` | string or null | No | Its name. The definition's own, made free in the project, unless you say. | | `project_id` | string (uuid) | Yes | The project the agent is made in. | ## Answer `201` with [AgentWritten](/reference/objects/AgentWritten). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such project. | | `409` | The project already has an agent with that name, or it is frozen. | | `422` | The definition cannot be read, or holds something an agent may not. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Create an agent from a definition. It is a draft until it is published. With a live key. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/agents" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "definition": { "format": "agently.agent/1", "agent": { "name": "Aigently front desk", "kind": "custom", "direction": "outbound", "system_prompt": "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking." }, "references": {} } }' ``` **JavaScript** ```js // Create an agent from a definition. It is a draft until it is published. With a live key. const response = await fetch("https://api.aigently.ai/v1/agents", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "definition": { "format": "agently.agent/1", "agent": { "name": "Aigently front desk", "kind": "custom", "direction": "outbound", "system_prompt": "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking." }, "references": {} } }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Create an agent from a definition. It is a draft until it is published. With a live key. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/agents", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "definition": { "format": "agently.agent/1", "agent": { "name": "Aigently front desk", "kind": "custom", "direction": "outbound", "system_prompt": "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking.", }, "references": {}, }, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Create an agent from a definition. It is a draft until it is published. With a live key. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "definition": { "format": "agently.agent/1", "agent": { "name": "Aigently front desk", "kind": "custom", "direction": "outbound", "system_prompt": "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking." }, "references": {} } }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/agents", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Create an agent from a definition. It is a draft until it is published. With a live 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 { String body = """ { "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "definition": { "format": "agently.agent/1", "agent": { "name": "Aigently front desk", "kind": "custom", "direction": "outbound", "system_prompt": "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking." }, "references": {} } } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/agents")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Create an agent from a definition. It is a draft until it is published. With a live 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.Post, "https://api.aigently.ai/v1/agents") { Content = new StringContent( """ { "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "definition": { "format": "agently.agent/1", "agent": { "name": "Aigently front desk", "kind": "custom", "direction": "outbound", "system_prompt": "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking." }, "references": {} } } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "project_id" => "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "definition" => [ "format" => "agently.agent/1", "agent" => [ "name" => "Aigently front desk", "kind" => "custom", "direction" => "outbound", "system_prompt" => "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking.", ], "references" => new \stdClass(), ], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Get an agent > GET /v1/agents/{agent_id} One agent, with what a conversation can start with (`variables_schema`), the answers it collects (`collected_schema`), what its analysis writes (`analysis_schema`), its languages and its numbers. Needs `agents:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `agent_id` | path | string (uuid) | Yes | | ## Answer `200` with [AgentDetail](/reference/objects/AgentDetail). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such agent. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Read an agent and its variables curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read an agent and its variables const response = await fetch("https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", { 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 # Read an agent and its variables # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read an agent and its variables package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", 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 // Read an agent and its variables 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/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c")) .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 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 // Read an agent and its variables 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/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c") { }; 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 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"; ``` --- # Delete an agent > DELETE /v1/agents/{agent_id} Take the agent off the air and put it in the trash. Its conversations, recordings and numbers stay with it for 30 days, while the console can restore it; then it is gone for good. Needs `agents:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `agent_id` | path | string (uuid) | Yes | | ## Answer `200` with [AgentDeleted](/reference/objects/AgentDeleted). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such agent. | | `409` | The project is frozen. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Delete an agent. The console can restore it for 30 days. With a live key. curl -sS --fail-with-body -X DELETE "https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Delete an agent. The console can restore it for 30 days. With a live key. const response = await fetch("https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a", { method: "DELETE", 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 # Delete an agent. The console can restore it for 30 days. With a live key. # pip install httpx import os import httpx response = httpx.delete( "https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Delete an agent. The console can restore it for 30 days. With a live key. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("DELETE", "https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a", 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 // Delete an agent. The console can restore it for 30 days. With a live 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/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("DELETE", 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 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 // Delete an agent. The console can restore it for 30 days. With a live 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.Delete, "https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a") { }; 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 "DELETE", 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"; ``` --- # Get an agent's definition > GET /v1/agents/{agent_id}/definition The whole agent as a document — its prompt, configuration, voice, languages and analysis, with every tool, knowledge base and calendar it uses by name. The console's own export format: keep it in a repository, change it, and put it back. Needs `agents:write`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `agent_id` | path | string (uuid) | Yes | | ## Answer `200` with [AgentDefinition](/reference/objects/AgentDefinition). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such agent. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Read an agent's whole definition. Keep it in your repository; put it back with PUT. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/definition" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read an agent's whole definition. Keep it in your repository; put it back with PUT. const response = await fetch("https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/definition", { 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 # Read an agent's whole definition. Keep it in your repository; put it back with PUT. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/definition", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read an agent's whole definition. Keep it in your repository; put it back with PUT. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/definition", 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 // Read an agent's whole definition. Keep it in your repository; put it back with PUT. 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/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/definition")) .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 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 // Read an agent's whole definition. Keep it in your repository; put it back with PUT. 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/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/definition") { }; 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 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"; ``` --- # Replace an agent's definition > PUT /v1/agents/{agent_id}/definition Put a definition back onto an agent: its prompt, configuration, voice, languages, analysis, and the tools and knowledge bases it names. On a published agent the change is live at once, as an edit in the console is, until the next publish freezes it as a version. Needs `agents:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `agent_id` | path | string (uuid) | Yes | | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `definition` | object | Yes | The agent's new definition. Its kind and direction must be the agent's own. | | `name` | string or null | No | A new name, if it is to change. | ## Answer `200` with [AgentWritten](/reference/objects/AgentWritten). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such agent. | | `409` | The project already has an agent with that name, or it is frozen. | | `422` | The definition cannot be read, holds something an agent may not, or is for another kind or direction of agent. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Replace an agent's definition. On a published agent the change is live at once. With a live key. curl -sS --fail-with-body -X PUT "https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a/definition" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "definition": { "format": "agently.agent/1", "agent": { "name": "Aigently front desk", "kind": "custom", "direction": "outbound", "system_prompt": "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking." }, "references": {} } }' ``` **JavaScript** ```js // Replace an agent's definition. On a published agent the change is live at once. With a live key. const response = await fetch("https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a/definition", { method: "PUT", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "definition": { "format": "agently.agent/1", "agent": { "name": "Aigently front desk", "kind": "custom", "direction": "outbound", "system_prompt": "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking." }, "references": {} } }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Replace an agent's definition. On a published agent the change is live at once. With a live key. # pip install httpx import os import httpx response = httpx.put( "https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a/definition", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "definition": { "format": "agently.agent/1", "agent": { "name": "Aigently front desk", "kind": "custom", "direction": "outbound", "system_prompt": "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking.", }, "references": {}, }, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Replace an agent's definition. On a published agent the change is live at once. With a live key. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "definition": { "format": "agently.agent/1", "agent": { "name": "Aigently front desk", "kind": "custom", "direction": "outbound", "system_prompt": "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking." }, "references": {} } }`) request, err := http.NewRequest("PUT", "https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a/definition", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Replace an agent's definition. On a published agent the change is live at once. With a live 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 { String body = """ { "definition": { "format": "agently.agent/1", "agent": { "name": "Aigently front desk", "kind": "custom", "direction": "outbound", "system_prompt": "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking." }, "references": {} } } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a/definition")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("PUT", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Replace an agent's definition. On a published agent the change is live at once. With a live 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.Put, "https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a/definition") { Content = new StringContent( """ { "definition": { "format": "agently.agent/1", "agent": { "name": "Aigently front desk", "kind": "custom", "direction": "outbound", "system_prompt": "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking." }, "references": {} } } """, Encoding.UTF8, "application/json"), }; 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 "PUT", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "definition" => [ "format" => "agently.agent/1", "agent" => [ "name" => "Aigently front desk", "kind" => "custom", "direction" => "outbound", "system_prompt" => "You are the Aigently front desk. Greet {{first_name}} by name and confirm their booking.", ], "references" => new \stdClass(), ], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Publish an agent > POST /v1/agents/{agent_id}/publish Put the agent live and freeze what went live as its next version — after the console's own Publish check, rehearsals and provider checks included. Refused with every reason it is not ready. Needs `agents:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `agent_id` | path | string (uuid) | Yes | | ## Answer `201` with [AgentVersionObject](/reference/objects/AgentVersionObject). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such agent. | | `409` | The agent is not ready — `errors` lists every reason, as the console does — or its project is frozen. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Publish an agent. Runs the console's Publish check first. With a live key. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a/publish" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "note": "Booking wording" }' ``` **JavaScript** ```js // Publish an agent. Runs the console's Publish check first. With a live key. const response = await fetch("https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a/publish", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "note": "Booking wording" }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Publish an agent. Runs the console's Publish check first. With a live key. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a/publish", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "note": "Booking wording", }, timeout=60, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Publish an agent. Runs the console's Publish check first. With a live key. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "note": "Booking wording" }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a/publish", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Publish an agent. Runs the console's Publish check first. With a live 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 { String body = """ { "note": "Booking wording" } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a/publish")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Publish an agent. Runs the console's Publish check first. With a live 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.Post, "https://api.aigently.ai/v1/agents/9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a/publish") { Content = new StringContent( """ { "note": "Booking wording" } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "note" => "Booking wording", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # List an agent's versions > GET /v1/agents/{agent_id}/versions Every version the agent was published as, newest first, each with the values a conversation pinned to it takes. Pin a call, a chat or a browser call to one with `agent_version`. Needs `agents:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `agent_id` | path | string (uuid) | Yes | | | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [AgentVersionList](/reference/objects/AgentVersionList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such agent. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # List the versions an agent was published as. Pin a call, a chat or a browser call to one with `agent_version`. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/versions" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List the versions an agent was published as. Pin a call, a chat or a browser call to one with `agent_version`. const response = await fetch("https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/versions", { 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 # List the versions an agent was published as. Pin a call, a chat or a browser call to one with `agent_version`. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/versions", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List the versions an agent was published as. Pin a call, a chat or a browser call to one with `agent_version`. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/versions", 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 // List the versions an agent was published as. Pin a call, a chat or a browser call to one with `agent_version`. 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/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/versions")) .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 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 // List the versions an agent was published as. Pin a call, a chat or a browser call to one with `agent_version`. 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/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/versions") { }; 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 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"; ``` --- # Get a published version's definition > GET /v1/agents/{agent_id}/versions/{version}/definition One published version as a document, to compare with what is in your repository or to put back. Its tools and knowledge bases are the agent's as they are now: a version freezes how the agent behaves, not what it is attached to. Needs `agents:write`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `agent_id` | path | string (uuid) | Yes | | | `version` | path | integer | Yes | | ## Answer `200` with [AgentDefinition](/reference/objects/AgentDefinition). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such agent, or the agent has no such version. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Read a published version's definition curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/versions/1/definition" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read a published version's definition const response = await fetch("https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/versions/1/definition", { 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 # Read a published version's definition # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/versions/1/definition", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read a published version's definition package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/versions/1/definition", 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 // Read a published version's definition 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/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/versions/1/definition")) .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 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 // Read a published version's definition 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/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/versions/1/definition") { }; 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 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"; ``` --- # Run an agent's evaluations > POST /v1/agents/{agent_id}/evaluation-runs Rehearse every saved conversation the agent has, against the agent as it is now, and judge each one. Answers at once with the run, `queued`: read it with `GET /v1/evaluation-runs/{id}` until its `status` is `finished`. Each run is charged as testing. Needs `evaluations:run`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `agent_id` | path | string (uuid) | Yes | | ## Answer `202` with [EvaluationRunObject](/reference/objects/EvaluationRunObject). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `402` | The organization's credit is used up. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such agent. | | `409` | Saved conversations are already being rehearsed in this organization, or the project is frozen. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Run an agent's evaluations. It answers at once. Read the run until its status is finished. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluation-runs" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Run an agent's evaluations. It answers at once. Read the run until its status is finished. const response = await fetch("https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluation-runs", { method: "POST", 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 # Run an agent's evaluations. It answers at once. Read the run until its status is finished. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluation-runs", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Run an agent's evaluations. It answers at once. Read the run until its status is finished. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluation-runs", 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 // Run an agent's evaluations. It answers at once. Read the run until its status is finished. 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/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluation-runs")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("POST", 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 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 // Run an agent's evaluations. It answers at once. Read the run until its status is finished. 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.Post, "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluation-runs") { }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => "", ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # List an agent's evaluations > GET /v1/agents/{agent_id}/evaluations The conversations an agent has to keep handling, in the order they were written, each with its most recent result. Needs `evaluations:run`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `agent_id` | path | string (uuid) | Yes | | ## Answer `200` with [EvaluationList](/reference/objects/EvaluationList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such agent. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # List an agent's evaluations curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluations" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List an agent's evaluations const response = await fetch("https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluations", { 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 # List an agent's evaluations # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluations", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List an agent's evaluations package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluations", 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 // List an agent's evaluations 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/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluations")) .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 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 // List an agent's evaluations 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/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluations") { }; 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 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"; ``` --- # Add an evaluation > POST /v1/agents/{agent_id}/evaluations Write down a conversation the agent has to keep handling: what the caller says, and what must be true of the replies. Publishing then rehearses it, and refuses while it fails. Needs `agents:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `agent_id` | path | string (uuid) | Yes | | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `expectations` | array of [EvaluationExpectationCreate](/reference/objects/EvaluationExpectationCreate) | Yes | | | `name` | string | Yes | | | `turns` | array of string | Yes | What the caller says, in order. | ## Answer `201` with [EvaluationObject](/reference/objects/EvaluationObject). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A test key, or a key without `agents:write`. | | `404` | This key reaches no such agent. | | `409` | The agent has one by that name, or as many as it can keep, or its project is frozen. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Add an evaluation. Publishing rehearses it from now on. With a live key. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluations" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "name": "Asks for the opening hours", "turns": [ "What time do you open tomorrow?", "And on Sundays?" ], "expectations": [ { "id": "gave_hours", "text": "The agent says when the restaurant opens." }, { "id": "no_invented_offers", "text": "The agent offers no discount it was not told about." } ] }' ``` **JavaScript** ```js // Add an evaluation. Publishing rehearses it from now on. With a live key. const response = await fetch("https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluations", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "name": "Asks for the opening hours", "turns": [ "What time do you open tomorrow?", "And on Sundays?" ], "expectations": [ { "id": "gave_hours", "text": "The agent says when the restaurant opens." }, { "id": "no_invented_offers", "text": "The agent offers no discount it was not told about." } ] }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Add an evaluation. Publishing rehearses it from now on. With a live key. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluations", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "name": "Asks for the opening hours", "turns": ["What time do you open tomorrow?", "And on Sundays?"], "expectations": [{"id": "gave_hours", "text": "The agent says when the restaurant opens."}, {"id": "no_invented_offers", "text": "The agent offers no discount it was not told about."}], }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Add an evaluation. Publishing rehearses it from now on. With a live key. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "name": "Asks for the opening hours", "turns": [ "What time do you open tomorrow?", "And on Sundays?" ], "expectations": [ { "id": "gave_hours", "text": "The agent says when the restaurant opens." }, { "id": "no_invented_offers", "text": "The agent offers no discount it was not told about." } ] }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluations", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Add an evaluation. Publishing rehearses it from now on. With a live 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 { String body = """ { "name": "Asks for the opening hours", "turns": [ "What time do you open tomorrow?", "And on Sundays?" ], "expectations": [ { "id": "gave_hours", "text": "The agent says when the restaurant opens." }, { "id": "no_invented_offers", "text": "The agent offers no discount it was not told about." } ] } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluations")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Add an evaluation. Publishing rehearses it from now on. With a live 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.Post, "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluations") { Content = new StringContent( """ { "name": "Asks for the opening hours", "turns": [ "What time do you open tomorrow?", "And on Sundays?" ], "expectations": [ { "id": "gave_hours", "text": "The agent says when the restaurant opens." }, { "id": "no_invented_offers", "text": "The agent offers no discount it was not told about." } ] } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "name" => "Asks for the opening hours", "turns" => ["What time do you open tomorrow?", "And on Sundays?"], "expectations" => [ [ "id" => "gave_hours", "text" => "The agent says when the restaurant opens.", ], [ "id" => "no_invented_offers", "text" => "The agent offers no discount it was not told about.", ], ], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Delete an evaluation > DELETE /v1/agents/{agent_id}/evaluations/{evaluation_id} Publishing stops rehearsing it, and its results go with it. Needs `agents:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `agent_id` | path | string (uuid) | Yes | | | `evaluation_id` | path | string (uuid) | Yes | | ## Answer `200` with [Removed](/reference/objects/Removed). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such agent or evaluation. | | `409` | The project is frozen. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Delete an evaluation. With a live key. curl -sS --fail-with-body -X DELETE "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluations/3f5b7d9f-1b3d-4f5b-e7d9-f1b3d5f7b9db" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Delete an evaluation. With a live key. const response = await fetch("https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluations/3f5b7d9f-1b3d-4f5b-e7d9-f1b3d5f7b9db", { method: "DELETE", 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 # Delete an evaluation. With a live key. # pip install httpx import os import httpx response = httpx.delete( "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluations/3f5b7d9f-1b3d-4f5b-e7d9-f1b3d5f7b9db", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Delete an evaluation. With a live key. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("DELETE", "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluations/3f5b7d9f-1b3d-4f5b-e7d9-f1b3d5f7b9db", 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 // Delete an evaluation. With a live 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/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluations/3f5b7d9f-1b3d-4f5b-e7d9-f1b3d5f7b9db")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("DELETE", 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 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 // Delete an evaluation. With a live 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.Delete, "https://api.aigently.ai/v1/agents/8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c/evaluations/3f5b7d9f-1b3d-4f5b-e7d9-f1b3d5f7b9db") { }; 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 "DELETE", 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"; ``` --- # Get an evaluation run > GET /v1/evaluation-runs/{run_id} How a run is going, and once `status` is `finished`, how every saved conversation did. Fail your build on `failed`; a conversation that is `not_checked` could not be rehearsed, which says nothing about the agent. Needs `evaluations:run`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `run_id` | path | string (uuid) | Yes | | ## Answer `200` with [EvaluationRunObject](/reference/objects/EvaluationRunObject). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such run. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Read how an evaluation run did. Fail your build on failed; not_checked says nothing about the agent. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/evaluation-runs/4a6c8e0a-2c4e-4a6c-f8e0-a2c4e6a8cafc" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read how an evaluation run did. Fail your build on failed; not_checked says nothing about the agent. const response = await fetch("https://api.aigently.ai/v1/evaluation-runs/4a6c8e0a-2c4e-4a6c-f8e0-a2c4e6a8cafc", { 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 # Read how an evaluation run did. Fail your build on failed; not_checked says nothing about the agent. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/evaluation-runs/4a6c8e0a-2c4e-4a6c-f8e0-a2c4e6a8cafc", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read how an evaluation run did. Fail your build on failed; not_checked says nothing about the agent. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/evaluation-runs/4a6c8e0a-2c4e-4a6c-f8e0-a2c4e6a8cafc", 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 // Read how an evaluation run did. Fail your build on failed; not_checked says nothing about the agent. 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/evaluation-runs/4a6c8e0a-2c4e-4a6c-f8e0-a2c4e6a8cafc")) .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 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 // Read how an evaluation run did. Fail your build on failed; not_checked says nothing about the agent. 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/evaluation-runs/4a6c8e0a-2c4e-4a6c-f8e0-a2c4e6a8cafc") { }; 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 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"; ``` --- # List phone numbers > GET /v1/phone-numbers The numbers in the projects this key can reach, oldest first: which way each carries calls, and the agent it belongs to. Needs `phone_numbers:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `project_id` | query | string (uuid) or null | No | Only this project's. | | `agent_id` | query | string (uuid) or null | No | Only the numbers this agent owns or may call from. | | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [PhoneNumberList](/reference/objects/PhoneNumberList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # List phone numbers curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/phone-numbers" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List phone numbers const response = await fetch("https://api.aigently.ai/v1/phone-numbers", { 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 # List phone numbers # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/phone-numbers", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List phone numbers package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/phone-numbers", 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 // List phone numbers 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/phone-numbers")) .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 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 // List phone numbers 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/phone-numbers") { }; 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 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"; ``` --- # Point a phone number at an agent > PATCH /v1/phone-numbers/{phone_number_id} Choose the agent a number belongs to: the one that answers when it is called, or — for a number that only places calls — the outbound agent that calls from it. `null` leaves it with no agent. The agent must be in the number's project. It takes effect on the next call. A test key cannot do this, because a phone number is real. Needs `phone_numbers:write`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `phone_number_id` | path | string (uuid) | Yes | | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `agent_id` | string (uuid) or null | Yes | The agent the number belongs to, in the number's project — or `null` for none. Required: leaving it out is not the same as `null`. | ## Answer `200` with [PhoneNumber](/reference/objects/PhoneNumber). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A test key, or a number another agent holds that this key does not reach. | | `404` | This key reaches no such number, or no such agent in the number's project. | | `409` | The number and the agent want different things, or the project is frozen. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | | `501` | This deployment has no telephony. | ## Examples **curl** ```sh #!/bin/sh # Point a number at an agent. With a live key: a phone number is real. curl -sS --fail-with-body -X PATCH "https://api.aigently.ai/v1/phone-numbers/7a9c1e3f-5b7d-4f9a-8c2e-4d6f8a0c2e4a" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f" }' ``` **JavaScript** ```js // Point a number at an agent. With a live key: a phone number is real. const response = await fetch("https://api.aigently.ai/v1/phone-numbers/7a9c1e3f-5b7d-4f9a-8c2e-4d6f8a0c2e4a", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f" }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Point a number at an agent. With a live key: a phone number is real. # pip install httpx import os import httpx response = httpx.patch( "https://api.aigently.ai/v1/phone-numbers/7a9c1e3f-5b7d-4f9a-8c2e-4d6f8a0c2e4a", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Point a number at an agent. With a live key: a phone number is real. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f" }`) request, err := http.NewRequest("PATCH", "https://api.aigently.ai/v1/phone-numbers/7a9c1e3f-5b7d-4f9a-8c2e-4d6f8a0c2e4a", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Point a number at an agent. With a live key: a phone number is real. 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 { String body = """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f" } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/phone-numbers/7a9c1e3f-5b7d-4f9a-8c2e-4d6f8a0c2e4a")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("PATCH", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Point a number at an agent. With a live key: a phone number is real. 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.Patch, "https://api.aigently.ai/v1/phone-numbers/7a9c1e3f-5b7d-4f9a-8c2e-4d6f8a0c2e4a") { Content = new StringContent( """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f" } """, Encoding.UTF8, "application/json"), }; 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 "PATCH", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "agent_id" => "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Place a call > POST /v1/calls Call a phone number with one of your outbound agents. Answers `201` with the conversation, `pending` until the phone is answered. Needs `calls:write` and an `Idempotency-Key`: the same request sent again with the same key returns the same conversation instead of calling twice. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string | Yes | Your own id for this call, up to 120 characters. Required. | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `agent_id` | string (uuid) | Yes | The outbound agent that makes the call. | | `agent_version` | integer or null | No | Answer with this published version of the agent rather than what is live now — its number from `GET /v1/agents/{id}/versions`. Its values and languages are that version's, and every turn of the conversation keeps it. | | `call_window` | [CallWindow](/reference/objects/CallWindow) or null | No | Only start the call within these hours. Outside them it is refused with `outside_call_window`, which says when the window opens — schedule it for then with `POST /v1/scheduled-calls`. | | `external_id` | string or null | No | | | `from_number` | string or null | No | One of the agent's numbers to call from. Or send `phone_number_id`, never both; with neither, the agent's own number. | | `language` | string or null | No | One of the agent's language versions, like `ar`. | | `metadata` | object | No | Your own data, returned on every read and event. The agent never sees it. | | `phone_number_id` | string (uuid) or null | No | One of the agent's numbers to call from, by its id. | | `to_number` | string | Yes | The number to call, in international format, like `+966501234567`. | | `variables` | object | No | Values for the agent's `{{placeholders}}` — text, numbers or true/false. See the agent's `variables_schema`. | ## Answer `201` with [Conversation](/reference/objects/Conversation). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `400` | No `Idempotency-Key`, or one longer than 120 characters. | | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `402` | The organization's credit is used up. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such agent. | | `409` | The agent does not place calls or is not published, or its project is frozen. | | `413` | The request is larger than 64 KB. | | `422` | A field, a variable, the number to call or the number to call from does not fit — or the `Idempotency-Key` was already used for a different request. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | | `501` | This deployment does not place phone calls. | | `502` | The call could not be placed. Try again shortly. | ## Examples **curl** ```sh #!/bin/sh # Place a call. With a test key this calls a test number and rings nobody. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/calls" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ -H "Idempotency-Key: lead-20931" \ --json '{ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" }' ``` **JavaScript** ```js // Place a call. With a test key this calls a test number and rings nobody. const response = await fetch("https://api.aigently.ai/v1/calls", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "lead-20931", }, body: JSON.stringify({ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Place a call. With a test key this calls a test number and rings nobody. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/calls", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", "Idempotency-Key": "lead-20931", }, json={ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "variables": { "first_name": "Sara", }, "metadata": { "crm_lead_id": "L-20931", }, "external_id": "lead-20931", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Place a call. With a test key this calls a test number and rings nobody. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/calls", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") request.Header.Set("Idempotency-Key", "lead-20931") 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 // Place a call. With a test key this calls a test number and rings nobody. 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 { String body = """ { "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/calls")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .header("Idempotency-Key", "lead-20931") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Place a call. With a test key this calls a test number and rings nobody. 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.Post, "https://api.aigently.ai/v1/calls") { Content = new StringContent( """ { "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" } """, Encoding.UTF8, "application/json"), }; request.Headers.Add("Idempotency-Key", "lead-20931"); 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", "Idempotency-Key: lead-20931", ], CURLOPT_POSTFIELDS => json_encode([ "agent_id" => "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number" => "+12025550100", "variables" => [ "first_name" => "Sara", ], "metadata" => [ "crm_lead_id" => "L-20931", ], "external_id" => "lead-20931", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # End a conversation > POST /v1/conversations/{conversation_id}/end End a call or a chat that is still going. A call that is still ringing is cancelled; one in progress ends with the agent's own goodbye. Always answers `200` with the conversation, so it is safe to send again. Needs `calls:write` for calls and `chats:write` for chats. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `conversation_id` | path | string (uuid) | Yes | | ## Answer `200` with [Conversation](/reference/objects/Conversation). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such conversation. | | `409` | A WhatsApp conversation, or a frozen project. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # End a call or a chat curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/end" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // End a call or a chat const response = await fetch("https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/end", { method: "POST", 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 # End a call or a chat # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/end", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // End a call or a chat package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/end", 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 // End a call or a chat 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/end")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("POST", 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 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 // End a call or a chat 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.Post, "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/end") { }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => "", ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # List scheduled calls > GET /v1/scheduled-calls The calls this key's side of test mode scheduled, newest first. Filter by `status`. Needs `calls:write`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `status` | query | [ScheduledCallStatus](/reference/objects/ScheduledCallStatus) or null | No | Only these: scheduled, placed, cancelled, failed. | | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [ScheduledCallList](/reference/objects/ScheduledCallList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # List the calls still waiting curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/scheduled-calls?status=scheduled" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List the calls still waiting const response = await fetch("https://api.aigently.ai/v1/scheduled-calls?status=scheduled", { 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 # List the calls still waiting # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/scheduled-calls", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "status": "scheduled", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List the calls still waiting package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/scheduled-calls?status=scheduled", 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 // List the calls still waiting 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/scheduled-calls?status=scheduled")) .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 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 // List the calls still waiting 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/scheduled-calls?status=scheduled") { }; 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 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"; ``` --- # Schedule a call > POST /v1/scheduled-calls The request `POST /v1/calls` takes, placed later: at `dial_at`, or at the first moment its `call_window` is open at or after it. Checked now, so a mistake is said now, and checked again when it is placed. Answers with the scheduled call; once placed, its `conversation_id` names the conversation, which sends the usual events. Needs `calls:write` and an `Idempotency-Key`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string | Yes | Your own id for this request, up to 120 characters. Required. | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `agent_id` | string (uuid) | Yes | The outbound agent that makes the call. | | `agent_version` | integer or null | No | Answer with this published version of the agent rather than what is live now — its number from `GET /v1/agents/{id}/versions`. Its values and languages are that version's, and every turn of the conversation keeps it. | | `call_window` | [CallWindow](/reference/objects/CallWindow) or null | No | Only start the call within these hours. Outside them it is refused with `outside_call_window`, which says when the window opens — schedule it for then with `POST /v1/scheduled-calls`. | | `dial_at` | string (date-time) or null | No | The earliest the call may be placed. Now unless you say; with a `call_window`, the window's first opening at or after it. At most 30 days ahead. | | `external_id` | string or null | No | | | `from_number` | string or null | No | One of the agent's numbers to call from. Or send `phone_number_id`, never both; with neither, the agent's own number. | | `language` | string or null | No | One of the agent's language versions, like `ar`. | | `metadata` | object | No | Your own data, returned on every read and event. The agent never sees it. | | `phone_number_id` | string (uuid) or null | No | One of the agent's numbers to call from, by its id. | | `to_number` | string | Yes | The number to call, in international format, like `+966501234567`. | | `variables` | object | No | Values for the agent's `{{placeholders}}` — text, numbers or true/false. See the agent's `variables_schema`. | ## Answer `201` with [ScheduledCall](/reference/objects/ScheduledCall). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `400` | No `Idempotency-Key`. | | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such agent. | | `409` | The agent does not place calls or is not published, its project is frozen, or the number is on the do-not-call list. | | `422` | A field, a variable, the window or the number does not fit, the time is more than 30 days ahead — or the `Idempotency-Key` was used for another request. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | | `501` | This deployment does not place phone calls. | ## Examples **curl** ```sh #!/bin/sh # Schedule a call inside calling hours. It is placed at the first moment the window is open at or after dial_at. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/scheduled-calls" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ -H "Idempotency-Key: reminder-20931" \ --json '{ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "dial_at": "2026-10-12T13:00:00Z", "call_window": { "timezone": "America/New_York", "start": "09:00", "end": "17:00", "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "variables": { "first_name": "Sara" }, "external_id": "reminder-20931" }' ``` **JavaScript** ```js // Schedule a call inside calling hours. It is placed at the first moment the window is open at or after dial_at. const response = await fetch("https://api.aigently.ai/v1/scheduled-calls", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "reminder-20931", }, body: JSON.stringify({ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "dial_at": "2026-10-12T13:00:00Z", "call_window": { "timezone": "America/New_York", "start": "09:00", "end": "17:00", "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "variables": { "first_name": "Sara" }, "external_id": "reminder-20931" }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Schedule a call inside calling hours. It is placed at the first moment the window is open at or after dial_at. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/scheduled-calls", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", "Idempotency-Key": "reminder-20931", }, json={ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "dial_at": "2026-10-12T13:00:00Z", "call_window": { "timezone": "America/New_York", "start": "09:00", "end": "17:00", "days": ["mon", "tue", "wed", "thu", "fri"], }, "variables": { "first_name": "Sara", }, "external_id": "reminder-20931", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Schedule a call inside calling hours. It is placed at the first moment the window is open at or after dial_at. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "dial_at": "2026-10-12T13:00:00Z", "call_window": { "timezone": "America/New_York", "start": "09:00", "end": "17:00", "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "variables": { "first_name": "Sara" }, "external_id": "reminder-20931" }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/scheduled-calls", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") request.Header.Set("Idempotency-Key", "reminder-20931") 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 // Schedule a call inside calling hours. It is placed at the first moment the window is open at or after dial_at. 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 { String body = """ { "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "dial_at": "2026-10-12T13:00:00Z", "call_window": { "timezone": "America/New_York", "start": "09:00", "end": "17:00", "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "variables": { "first_name": "Sara" }, "external_id": "reminder-20931" } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/scheduled-calls")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .header("Idempotency-Key", "reminder-20931") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Schedule a call inside calling hours. It is placed at the first moment the window is open at or after dial_at. 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.Post, "https://api.aigently.ai/v1/scheduled-calls") { Content = new StringContent( """ { "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number": "+12025550100", "dial_at": "2026-10-12T13:00:00Z", "call_window": { "timezone": "America/New_York", "start": "09:00", "end": "17:00", "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "variables": { "first_name": "Sara" }, "external_id": "reminder-20931" } """, Encoding.UTF8, "application/json"), }; request.Headers.Add("Idempotency-Key", "reminder-20931"); 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", "Idempotency-Key: reminder-20931", ], CURLOPT_POSTFIELDS => json_encode([ "agent_id" => "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "to_number" => "+12025550100", "dial_at" => "2026-10-12T13:00:00Z", "call_window" => [ "timezone" => "America/New_York", "start" => "09:00", "end" => "17:00", "days" => ["mon", "tue", "wed", "thu", "fri"], ], "variables" => [ "first_name" => "Sara", ], "external_id" => "reminder-20931", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Get a scheduled call > GET /v1/scheduled-calls/{scheduled_call_id} One scheduled call: when it will be placed, or what became of it. `calls:write`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `scheduled_call_id` | path | string (uuid) | Yes | | ## Answer `200` with [ScheduledCall](/reference/objects/ScheduledCall). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such scheduled call. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Read a scheduled call. Once it is placed, conversation_id names the conversation. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/scheduled-calls/4b6d8f0a-2c4e-4a6c-9e8a-0c2e4a6c8e0b" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read a scheduled call. Once it is placed, conversation_id names the conversation. const response = await fetch("https://api.aigently.ai/v1/scheduled-calls/4b6d8f0a-2c4e-4a6c-9e8a-0c2e4a6c8e0b", { 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 # Read a scheduled call. Once it is placed, conversation_id names the conversation. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/scheduled-calls/4b6d8f0a-2c4e-4a6c-9e8a-0c2e4a6c8e0b", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read a scheduled call. Once it is placed, conversation_id names the conversation. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/scheduled-calls/4b6d8f0a-2c4e-4a6c-9e8a-0c2e4a6c8e0b", 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 // Read a scheduled call. Once it is placed, conversation_id names the conversation. 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/scheduled-calls/4b6d8f0a-2c4e-4a6c-9e8a-0c2e4a6c8e0b")) .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 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 // Read a scheduled call. Once it is placed, conversation_id names the conversation. 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/scheduled-calls/4b6d8f0a-2c4e-4a6c-9e8a-0c2e4a6c8e0b") { }; 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 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"; ``` --- # Cancel a scheduled call > DELETE /v1/scheduled-calls/{scheduled_call_id} Call it off before its time. Answers with the scheduled call, `cancelled`. Once its time has come it can no longer be called off: one being placed answers `scheduled_call_placing`, and one placed is a conversation — end that with `POST /v1/conversations/{id}/end`. Needs `calls:write`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `scheduled_call_id` | path | string (uuid) | Yes | | ## Answer `200` with [ScheduledCall](/reference/objects/ScheduledCall). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such scheduled call. | | `409` | It is being placed right now, or was placed, refused or cancelled already — or its project is frozen. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Cancel a scheduled call. Only before its time: once placed, it is a conversation, which you end instead. curl -sS --fail-with-body -X DELETE "https://api.aigently.ai/v1/scheduled-calls/4b6d8f0a-2c4e-4a6c-9e8a-0c2e4a6c8e0b" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Cancel a scheduled call. Only before its time: once placed, it is a conversation, which you end instead. const response = await fetch("https://api.aigently.ai/v1/scheduled-calls/4b6d8f0a-2c4e-4a6c-9e8a-0c2e4a6c8e0b", { method: "DELETE", 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 # Cancel a scheduled call. Only before its time: once placed, it is a conversation, which you end instead. # pip install httpx import os import httpx response = httpx.delete( "https://api.aigently.ai/v1/scheduled-calls/4b6d8f0a-2c4e-4a6c-9e8a-0c2e4a6c8e0b", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Cancel a scheduled call. Only before its time: once placed, it is a conversation, which you end instead. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("DELETE", "https://api.aigently.ai/v1/scheduled-calls/4b6d8f0a-2c4e-4a6c-9e8a-0c2e4a6c8e0b", 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 // Cancel a scheduled call. Only before its time: once placed, it is a conversation, which you end instead. 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/scheduled-calls/4b6d8f0a-2c4e-4a6c-9e8a-0c2e4a6c8e0b")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("DELETE", 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 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 // Cancel a scheduled call. Only before its time: once placed, it is a conversation, which you end instead. 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.Delete, "https://api.aigently.ai/v1/scheduled-calls/4b6d8f0a-2c4e-4a6c-9e8a-0c2e4a6c8e0b") { }; 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 "DELETE", 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"; ``` --- # List campaigns > GET /v1/campaigns Your campaigns, newest first, each with how many of its contacts are in each state. Filter by `agent_id` and `status`. A test key lists none: every campaign is live. Needs `campaigns:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `agent_id` | query | string (uuid) or null | No | Only this agent's. | | `status` | query | [CampaignStatus](/reference/objects/CampaignStatus) or null | No | Only campaigns in this state. | | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [CampaignList](/reference/objects/CampaignList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # List campaigns curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/campaigns?limit=10" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List campaigns const response = await fetch("https://api.aigently.ai/v1/campaigns?limit=10", { 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 # List campaigns # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/campaigns", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "limit": 10, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List campaigns package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/campaigns?limit=10", 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 // List campaigns 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/campaigns?limit=10")) .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 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 // List campaigns 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/campaigns?limit=10") { }; 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 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"; ``` --- # Create a campaign > POST /v1/campaigns A list of people for an outbound agent to call, at the pace and in the hours you set. It is a draft until it starts: send `start: true` to start dialling at once, `start_at` to start at a moment of your choosing, or neither and start it later. Up to 1,000 contacts in one request; add more with `POST /v1/campaigns/{id}/contacts`. Needs `campaigns:write`, a live key and an `Idempotency-Key`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string | Yes | Your own id for this request, up to 120 characters. Required. | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `agent_id` | string (uuid) | Yes | The outbound agent that makes the calls. | | `callbacks` | [CampaignCallbacks](/reference/objects/CampaignCallbacks) or null | No | | | `calling_hours` | [CampaignCallingHours](/reference/objects/CampaignCallingHours) or null | No | When calls may start, read in each contact's own `timezone` — or your organization's, for a contact without one. | | `contacts` | array of [CampaignContactCreate](/reference/objects/CampaignContactCreate) | No | The people to call, up to 1,000 in one request. | | `name` | string | Yes | What the campaign is called in the console. | | `pacing` | [CampaignPacing](/reference/objects/CampaignPacing) or null | No | | | `phone_number_id` | string (uuid) or null | No | One of the agent's numbers to call from. The agent's own unless you say. | | `start` | boolean | No | Start dialling now. | | `start_at` | string (date-time) or null | No | Start dialling at this moment instead, with its offset — `2026-10-12T09:00:00+03:00`. A time without one is UTC. | | `voicemail` | [CampaignVoicemail](/reference/objects/CampaignVoicemail) or null | No | | ## Answer `201` with [Campaign](/reference/objects/Campaign). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `400` | No `Idempotency-Key`. | | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A test key: a campaign rings real people. | | `404` | This key reaches no such agent, or no such number to call from. | | `409` | The agent answers calls rather than placing them, it cannot place a call yet — not published, no number to call from — or its project is frozen. | | `422` | A contact does not fit — `errors` names each by its place in `contacts` — the start time has passed, or the `Idempotency-Key` was used for another request. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | | `501` | This deployment does not place phone calls. | ## Examples **curl** ```sh #!/bin/sh # Create a campaign. With a live key: a campaign calls real people. It is a draft until you start it. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/campaigns" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ -H "Idempotency-Key: reminders-october" \ --json '{ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "name": "Visit reminders, October", "calling_hours": { "start_hour": 9, "end_hour": 18, "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "contacts": [ { "to_number": "+12025550123", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" }, { "to_number": "+12025550124", "variables": { "first_name": "Omar" }, "timezone": "America/Chicago", "external_id": "lead-20932" } ] }' ``` **JavaScript** ```js // Create a campaign. With a live key: a campaign calls real people. It is a draft until you start it. const response = await fetch("https://api.aigently.ai/v1/campaigns", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "reminders-october", }, body: JSON.stringify({ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "name": "Visit reminders, October", "calling_hours": { "start_hour": 9, "end_hour": 18, "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "contacts": [ { "to_number": "+12025550123", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" }, { "to_number": "+12025550124", "variables": { "first_name": "Omar" }, "timezone": "America/Chicago", "external_id": "lead-20932" } ] }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Create a campaign. With a live key: a campaign calls real people. It is a draft until you start it. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/campaigns", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", "Idempotency-Key": "reminders-october", }, json={ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "name": "Visit reminders, October", "calling_hours": { "start_hour": 9, "end_hour": 18, "days": ["mon", "tue", "wed", "thu", "fri"], }, "contacts": [{"to_number": "+12025550123", "variables": {"first_name": "Sara"}, "metadata": {"crm_lead_id": "L-20931"}, "external_id": "lead-20931"}, {"to_number": "+12025550124", "variables": {"first_name": "Omar"}, "timezone": "America/Chicago", "external_id": "lead-20932"}], }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Create a campaign. With a live key: a campaign calls real people. It is a draft until you start it. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "name": "Visit reminders, October", "calling_hours": { "start_hour": 9, "end_hour": 18, "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "contacts": [ { "to_number": "+12025550123", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" }, { "to_number": "+12025550124", "variables": { "first_name": "Omar" }, "timezone": "America/Chicago", "external_id": "lead-20932" } ] }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/campaigns", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") request.Header.Set("Idempotency-Key", "reminders-october") 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 // Create a campaign. With a live key: a campaign calls real people. It is a draft until you start it. 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 { String body = """ { "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "name": "Visit reminders, October", "calling_hours": { "start_hour": 9, "end_hour": 18, "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "contacts": [ { "to_number": "+12025550123", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" }, { "to_number": "+12025550124", "variables": { "first_name": "Omar" }, "timezone": "America/Chicago", "external_id": "lead-20932" } ] } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/campaigns")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .header("Idempotency-Key", "reminders-october") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Create a campaign. With a live key: a campaign calls real people. It is a draft until you start it. 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.Post, "https://api.aigently.ai/v1/campaigns") { Content = new StringContent( """ { "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "name": "Visit reminders, October", "calling_hours": { "start_hour": 9, "end_hour": 18, "days": [ "mon", "tue", "wed", "thu", "fri" ] }, "contacts": [ { "to_number": "+12025550123", "variables": { "first_name": "Sara" }, "metadata": { "crm_lead_id": "L-20931" }, "external_id": "lead-20931" }, { "to_number": "+12025550124", "variables": { "first_name": "Omar" }, "timezone": "America/Chicago", "external_id": "lead-20932" } ] } """, Encoding.UTF8, "application/json"), }; request.Headers.Add("Idempotency-Key", "reminders-october"); 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", "Idempotency-Key: reminders-october", ], CURLOPT_POSTFIELDS => json_encode([ "agent_id" => "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "name" => "Visit reminders, October", "calling_hours" => [ "start_hour" => 9, "end_hour" => 18, "days" => ["mon", "tue", "wed", "thu", "fri"], ], "contacts" => [ [ "to_number" => "+12025550123", "variables" => [ "first_name" => "Sara", ], "metadata" => [ "crm_lead_id" => "L-20931", ], "external_id" => "lead-20931", ], [ "to_number" => "+12025550124", "variables" => [ "first_name" => "Omar", ], "timezone" => "America/Chicago", "external_id" => "lead-20932", ], ], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Get a campaign > GET /v1/campaigns/{campaign_id} One campaign: its settings, its state, and how many of its contacts are waiting, being called, done or given up on. Needs `campaigns:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `campaign_id` | path | string (uuid) | Yes | | ## Answer `200` with [Campaign](/reference/objects/Campaign). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such campaign. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Read a campaign and its progress curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read a campaign and its progress const response = await fetch("https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b", { 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 # Read a campaign and its progress # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read a campaign and its progress package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b", 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 // Read a campaign and its progress 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/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b")) .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 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 // Read a campaign and its progress 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/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b") { }; 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 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"; ``` --- # Cancel a campaign > POST /v1/campaigns/{campaign_id}/cancel Stop it for good: nobody else on the list is called. Calls already in progress carry on. A cancelled campaign cannot be started again. Needs `campaigns:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `campaign_id` | path | string (uuid) | Yes | | ## Answer `200` with [Campaign](/reference/objects/Campaign). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A test key: a campaign rings real people. | | `404` | This key reaches no such campaign. | | `409` | The campaign is not in a state this applies to, or has finished. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Cancel a campaign. For good: nobody else on the list is called. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/cancel" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Cancel a campaign. For good: nobody else on the list is called. const response = await fetch("https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/cancel", { method: "POST", 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 # Cancel a campaign. For good: nobody else on the list is called. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/cancel", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Cancel a campaign. For good: nobody else on the list is called. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/cancel", 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 // Cancel a campaign. For good: nobody else on the list is called. 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/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/cancel")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("POST", 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 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 // Cancel a campaign. For good: nobody else on the list is called. 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.Post, "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/cancel") { }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => "", ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # List a campaign's contacts > GET /v1/campaigns/{campaign_id}/contacts Each person in the campaign and how it went: waiting, being called, done, given up on after every try, or not called at all and why — with the last conversation, your own `metadata` and `external_id`. In the order they were added. Filter by `status`. Needs `campaigns:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `campaign_id` | path | string (uuid) | Yes | | | `status` | query | [CampaignContactStatus](/reference/objects/CampaignContactStatus) or null | No | Only contacts in this state. | | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [CampaignContactList](/reference/objects/CampaignContactList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such campaign. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # See how each call in a campaign went curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts?status=done" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // See how each call in a campaign went const response = await fetch("https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts?status=done", { 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 # See how each call in a campaign went # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "status": "done", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // See how each call in a campaign went package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts?status=done", 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 // See how each call in a campaign went 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/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts?status=done")) .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 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 // See how each call in a campaign went 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/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts?status=done") { }; 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 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"; ``` --- # Add contacts to a campaign > POST /v1/campaigns/{campaign_id}/contacts Up to 1,000 more people, to a campaign that is a draft, running or paused. A running campaign starts calling them in its next calling hours. A number the campaign already holds is skipped and listed in `already_in_campaign`, so sending a batch again is safe. Needs `campaigns:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `campaign_id` | path | string (uuid) | Yes | | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `contacts` | array of [CampaignContactCreate](/reference/objects/CampaignContactCreate) | Yes | The people to add, up to 1,000 in one request. | ## Answer `200` with [CampaignContactsAdded](/reference/objects/CampaignContactsAdded). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A test key: a campaign rings real people. | | `404` | This key reaches no such campaign. | | `409` | The campaign has finished: create a new one for a new list. | | `422` | A contact does not fit — `errors` names each by its place in `contacts`. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Add people to a campaign. A number the campaign already holds is skipped, so sending a batch again is safe. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "contacts": [ { "to_number": "+12025550125", "variables": { "first_name": "Lina" }, "external_id": "lead-20933" } ] }' ``` **JavaScript** ```js // Add people to a campaign. A number the campaign already holds is skipped, so sending a batch again is safe. const response = await fetch("https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "contacts": [ { "to_number": "+12025550125", "variables": { "first_name": "Lina" }, "external_id": "lead-20933" } ] }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Add people to a campaign. A number the campaign already holds is skipped, so sending a batch again is safe. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "contacts": [{"to_number": "+12025550125", "variables": {"first_name": "Lina"}, "external_id": "lead-20933"}], }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Add people to a campaign. A number the campaign already holds is skipped, so sending a batch again is safe. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "contacts": [ { "to_number": "+12025550125", "variables": { "first_name": "Lina" }, "external_id": "lead-20933" } ] }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Add people to a campaign. A number the campaign already holds is skipped, so sending a batch again is safe. 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 { String body = """ { "contacts": [ { "to_number": "+12025550125", "variables": { "first_name": "Lina" }, "external_id": "lead-20933" } ] } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Add people to a campaign. A number the campaign already holds is skipped, so sending a batch again is safe. 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.Post, "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/contacts") { Content = new StringContent( """ { "contacts": [ { "to_number": "+12025550125", "variables": { "first_name": "Lina" }, "external_id": "lead-20933" } ] } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "contacts" => [ [ "to_number" => "+12025550125", "variables" => [ "first_name" => "Lina", ], "external_id" => "lead-20933", ], ], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Pause a campaign > POST /v1/campaigns/{campaign_id}/pause Stop placing new calls. Calls already in progress carry on, and every contact keeps its place, so resuming picks up where it stopped. Pausing a paused campaign answers it as it is. Needs `campaigns:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `campaign_id` | path | string (uuid) | Yes | | ## Answer `200` with [Campaign](/reference/objects/Campaign). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A test key: a campaign rings real people. | | `404` | This key reaches no such campaign. | | `409` | The campaign is not in a state this applies to, or has finished. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Pause a campaign. Calls in progress carry on; nobody new is called until you resume it. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/pause" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Pause a campaign. Calls in progress carry on; nobody new is called until you resume it. const response = await fetch("https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/pause", { method: "POST", 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 # Pause a campaign. Calls in progress carry on; nobody new is called until you resume it. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/pause", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Pause a campaign. Calls in progress carry on; nobody new is called until you resume it. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/pause", 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 // Pause a campaign. Calls in progress carry on; nobody new is called until you resume it. 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/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/pause")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("POST", 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 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 // Pause a campaign. Calls in progress carry on; nobody new is called until you resume it. 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.Post, "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/pause") { }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => "", ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Resume a campaign > POST /v1/campaigns/{campaign_id}/resume Start a paused campaign dialling again. With `reset_attempts`, everybody not reached so far gets every try back. Checked like a start. Needs `campaigns:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `campaign_id` | path | string (uuid) | Yes | | ## Answer `200` with [Campaign](/reference/objects/Campaign). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A test key: a campaign rings real people. | | `404` | This key reaches no such campaign. | | `409` | The campaign is not in a state this applies to, or has finished. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | | `501` | This deployment does not place phone calls. | ## Examples **curl** ```sh #!/bin/sh # Resume a campaign curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/resume" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "reset_attempts": false }' ``` **JavaScript** ```js // Resume a campaign const response = await fetch("https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/resume", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "reset_attempts": false }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Resume a campaign # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/resume", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "reset_attempts": False, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Resume a campaign package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "reset_attempts": false }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/resume", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Resume a campaign 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 { String body = """ { "reset_attempts": false } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/resume")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Resume a campaign 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.Post, "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/resume") { Content = new StringContent( """ { "reset_attempts": false } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "reset_attempts" => false, ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Start a campaign > POST /v1/campaigns/{campaign_id}/start Start dialling a draft now, in its calling hours. Checked first: a campaign that cannot place a single call is refused here, not left running. Starting one that is running answers it as it is. Needs `campaigns:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `campaign_id` | path | string (uuid) | Yes | | ## Answer `200` with [Campaign](/reference/objects/Campaign). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A test key: a campaign rings real people. | | `404` | This key reaches no such campaign. | | `409` | The campaign has finished, or cannot place a call yet: the agent is not published, it has no number to call from, or contacts lack a value the agent says out loud. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | | `501` | This deployment does not place phone calls. | ## Examples **curl** ```sh #!/bin/sh # Start a campaign curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/start" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Start a campaign const response = await fetch("https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/start", { method: "POST", 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 # Start a campaign # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/start", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Start a campaign package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/start", 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 // Start a campaign 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/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/start")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("POST", 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 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 // Start a campaign 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.Post, "https://api.aigently.ai/v1/campaigns/1c3e5a7b-9d0f-4b2c-8e4a-6c8e0a2c4e6b/start") { }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => "", ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # List contacts > GET /v1/contacts The people in your phonebook, newest first. `phone` finds one person by their number; `project_id` keeps to one project. A test key lists none. Needs `contacts:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `project_id` | query | string (uuid) or null | No | Only this project's. | | `phone` | query | string or null | No | Only the person with this number. | | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [ContactList](/reference/objects/ContactList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Find someone in the phonebook by their number curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/contacts?phone=+12025550131" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Find someone in the phonebook by their number const response = await fetch("https://api.aigently.ai/v1/contacts?phone=+12025550131", { 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 # Find someone in the phonebook by their number # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/contacts", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "phone": "+12025550131", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Find someone in the phonebook by their number package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/contacts?phone=+12025550131", 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 // Find someone in the phonebook by their number 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/contacts?phone=+12025550131")) .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 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 // Find someone in the phonebook by their number 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/contacts?phone=+12025550131") { }; 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 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"; ``` --- # Add a contact > POST /v1/contacts One person to a project's phonebook: their number, the name the console shows, the `attributes` an agent can say about them, and their time zone. A number already there is `409 contact_exists` — to add or update many at once, import them. Needs `contacts:write` and a live key. ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `attributes` | object | No | What an agent may say about them: its `{{placeholders}}` take these by name. Kept as text. | | `name` | string | No | What the console calls them. Never spoken. | | `phone` | string | Yes | Their number, in international format. | | `project_id` | string (uuid) | Yes | The project whose phonebook they join. | | `timezone` | string or null | No | Where they are, like `Asia/Riyadh`: a campaign's calling hours are read there. Leave it out for your organization's own. | ## Answer `201` with [Contact](/reference/objects/Contact). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A test key, or a key limited to some agents. | | `404` | This key reaches no such project. | | `409` | The number is already in the project's phonebook, or the project is frozen. | | `422` | Not a phone number, or not a time zone. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Add someone to the phonebook. With a live key: the phonebook holds real people. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/contacts" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "phone": "+12025550131", "name": "Sara Haddad", "attributes": { "first_name": "Sara", "member_since": "2023" }, "timezone": "America/New_York" }' ``` **JavaScript** ```js // Add someone to the phonebook. With a live key: the phonebook holds real people. const response = await fetch("https://api.aigently.ai/v1/contacts", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "phone": "+12025550131", "name": "Sara Haddad", "attributes": { "first_name": "Sara", "member_since": "2023" }, "timezone": "America/New_York" }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Add someone to the phonebook. With a live key: the phonebook holds real people. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/contacts", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "phone": "+12025550131", "name": "Sara Haddad", "attributes": { "first_name": "Sara", "member_since": "2023", }, "timezone": "America/New_York", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Add someone to the phonebook. With a live key: the phonebook holds real people. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "phone": "+12025550131", "name": "Sara Haddad", "attributes": { "first_name": "Sara", "member_since": "2023" }, "timezone": "America/New_York" }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/contacts", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Add someone to the phonebook. With a live key: the phonebook holds real people. 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 { String body = """ { "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "phone": "+12025550131", "name": "Sara Haddad", "attributes": { "first_name": "Sara", "member_since": "2023" }, "timezone": "America/New_York" } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/contacts")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Add someone to the phonebook. With a live key: the phonebook holds real people. 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.Post, "https://api.aigently.ai/v1/contacts") { Content = new StringContent( """ { "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "phone": "+12025550131", "name": "Sara Haddad", "attributes": { "first_name": "Sara", "member_since": "2023" }, "timezone": "America/New_York" } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "project_id" => "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "phone" => "+12025550131", "name" => "Sara Haddad", "attributes" => [ "first_name" => "Sara", "member_since" => "2023", ], "timezone" => "America/New_York", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Import contacts > POST /v1/contacts/import Add up to 1,000 people to a project's phonebook in one request, matched by number: a number already there is updated, or left alone with `update_existing: false`. Rows that do not fit are listed in `errors` by their place in `contacts`, and the rest are taken — so sending a corrected list again is the way to fix it. Needs `contacts:write` and a live key. ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `contacts` | array of [ContactFields](/reference/objects/ContactFields) | Yes | The people, up to 1,000 in one request. | | `project_id` | string (uuid) | Yes | The project whose phonebook they join. | | `update_existing` | boolean | No | Whether a number already there takes these details. False leaves it as it is and counts it as skipped. | ## Answer `200` with [ContactImported](/reference/objects/ContactImported). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A test key, or a key limited to some agents. | | `404` | This key reaches no such project. | | `409` | The project is frozen. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Import a list into the phonebook. Matched by number: people already there are updated, so sending it again is safe. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/contacts/import" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "contacts": [ { "phone": "+12025550132", "name": "Omar Nasser", "attributes": { "first_name": "Omar" } }, { "phone": "+12025550133", "name": "Lina Saleh", "attributes": { "first_name": "Lina" } } ] }' ``` **JavaScript** ```js // Import a list into the phonebook. Matched by number: people already there are updated, so sending it again is safe. const response = await fetch("https://api.aigently.ai/v1/contacts/import", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "contacts": [ { "phone": "+12025550132", "name": "Omar Nasser", "attributes": { "first_name": "Omar" } }, { "phone": "+12025550133", "name": "Lina Saleh", "attributes": { "first_name": "Lina" } } ] }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Import a list into the phonebook. Matched by number: people already there are updated, so sending it again is safe. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/contacts/import", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "contacts": [{"phone": "+12025550132", "name": "Omar Nasser", "attributes": {"first_name": "Omar"}}, {"phone": "+12025550133", "name": "Lina Saleh", "attributes": {"first_name": "Lina"}}], }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Import a list into the phonebook. Matched by number: people already there are updated, so sending it again is safe. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "contacts": [ { "phone": "+12025550132", "name": "Omar Nasser", "attributes": { "first_name": "Omar" } }, { "phone": "+12025550133", "name": "Lina Saleh", "attributes": { "first_name": "Lina" } } ] }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/contacts/import", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Import a list into the phonebook. Matched by number: people already there are updated, so sending it again is safe. 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 { String body = """ { "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "contacts": [ { "phone": "+12025550132", "name": "Omar Nasser", "attributes": { "first_name": "Omar" } }, { "phone": "+12025550133", "name": "Lina Saleh", "attributes": { "first_name": "Lina" } } ] } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/contacts/import")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Import a list into the phonebook. Matched by number: people already there are updated, so sending it again is safe. 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.Post, "https://api.aigently.ai/v1/contacts/import") { Content = new StringContent( """ { "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "contacts": [ { "phone": "+12025550132", "name": "Omar Nasser", "attributes": { "first_name": "Omar" } }, { "phone": "+12025550133", "name": "Lina Saleh", "attributes": { "first_name": "Lina" } } ] } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "project_id" => "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "contacts" => [ [ "phone" => "+12025550132", "name" => "Omar Nasser", "attributes" => [ "first_name" => "Omar", ], ], [ "phone" => "+12025550133", "name" => "Lina Saleh", "attributes" => [ "first_name" => "Lina", ], ], ], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Get a contact > GET /v1/contacts/{contact_id} One person in your phonebook. Needs `contacts:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `contact_id` | path | string (uuid) | Yes | | ## Answer `200` with [Contact](/reference/objects/Contact). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such contact. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Read a contact curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read a contact const response = await fetch("https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d", { 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 # Read a contact # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read a contact package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d", 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 // Read a contact 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/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d")) .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 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 // Read a contact 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/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d") { }; 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 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"; ``` --- # Change a contact > PATCH /v1/contacts/{contact_id} Change what you send and keep the rest. `attributes` is replaced whole: send every attribute the person should have. Campaigns already made keep the details they copied; the next one, and the next inbound call, read these. Needs `contacts:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `contact_id` | path | string (uuid) | Yes | | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `attributes` | object or null | No | Replaces every attribute they had: send the whole set. | | `name` | string or null | No | | | `phone` | string or null | No | | | `timezone` | string or null | No | Send `null` for your organization's own time zone. | ## Answer `200` with [Contact](/reference/objects/Contact). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A test key, or a key limited to some agents. | | `404` | This key reaches no such contact. | | `409` | Another contact in the project has the new number, or it is frozen. | | `422` | Not a phone number, or not a time zone. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Change a contact. attributes is replaced whole: send every one they should have. curl -sS --fail-with-body -X PATCH "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "attributes": { "first_name": "Sara", "member_since": "2021" } }' ``` **JavaScript** ```js // Change a contact. attributes is replaced whole: send every one they should have. const response = await fetch("https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "attributes": { "first_name": "Sara", "member_since": "2021" } }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Change a contact. attributes is replaced whole: send every one they should have. # pip install httpx import os import httpx response = httpx.patch( "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "attributes": { "first_name": "Sara", "member_since": "2021", }, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Change a contact. attributes is replaced whole: send every one they should have. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "attributes": { "first_name": "Sara", "member_since": "2021" } }`) request, err := http.NewRequest("PATCH", "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Change a contact. attributes is replaced whole: send every one they should have. 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 { String body = """ { "attributes": { "first_name": "Sara", "member_since": "2021" } } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("PATCH", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Change a contact. attributes is replaced whole: send every one they should have. 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.Patch, "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d") { Content = new StringContent( """ { "attributes": { "first_name": "Sara", "member_since": "2021" } } """, Encoding.UTF8, "application/json"), }; 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 "PATCH", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "attributes" => [ "first_name" => "Sara", "member_since" => "2021", ], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Delete a contact > DELETE /v1/contacts/{contact_id} Take somebody out of your phonebook and every group they are in. The calls already made to them stay where they are. Needs `contacts:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `contact_id` | path | string (uuid) | Yes | | ## Answer `200` with [ContactDeleted](/reference/objects/ContactDeleted). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A test key, or a key limited to some agents. | | `404` | This key reaches no such contact. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Delete a contact. Calls already made to them stay where they are. curl -sS --fail-with-body -X DELETE "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Delete a contact. Calls already made to them stay where they are. const response = await fetch("https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d", { method: "DELETE", 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 # Delete a contact. Calls already made to them stay where they are. # pip install httpx import os import httpx response = httpx.delete( "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Delete a contact. Calls already made to them stay where they are. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("DELETE", "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d", 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 // Delete a contact. Calls already made to them stay where they are. 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/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("DELETE", 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 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 // Delete a contact. Calls already made to them stay where they are. 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.Delete, "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d") { }; 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 "DELETE", 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"; ``` --- # List knowledge bases > GET /v1/knowledge-bases Your knowledge bases, newest first, each with how many sources it holds. `project_id` keeps to one project. Needs `knowledge:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `project_id` | query | string (uuid) or null | No | Only this project's. | | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [KnowledgeBaseList](/reference/objects/KnowledgeBaseList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # List knowledge bases curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/knowledge-bases?project_id=0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List knowledge bases const response = await fetch("https://api.aigently.ai/v1/knowledge-bases?project_id=0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", { 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 # List knowledge bases # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/knowledge-bases", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List knowledge bases package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/knowledge-bases?project_id=0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", 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 // List knowledge bases 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/knowledge-bases?project_id=0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e")) .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 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 // List knowledge bases 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/knowledge-bases?project_id=0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e") { }; 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 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"; ``` --- # List the websites a knowledge base reads > GET /v1/knowledge-bases/{knowledge_base_id}/crawls Each website the base was given in the console, with how far its latest reading got. Needs `knowledge:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `knowledge_base_id` | path | string (uuid) | Yes | | ## Answer `200` with [KnowledgeCrawlList](/reference/objects/KnowledgeCrawlList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such knowledge base. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # List the websites a knowledge base reads curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List the websites a knowledge base reads const response = await fetch("https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls", { 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 # List the websites a knowledge base reads # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List the websites a knowledge base reads package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls", 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 // List the websites a knowledge base reads 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/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls")) .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 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 // List the websites a knowledge base reads 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/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls") { }; 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 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"; ``` --- # Read a website again > POST /v1/knowledge-bases/{knowledge_base_id}/crawls/{crawl_id}/refresh Read the website again now, as **Refresh** does in the console. Pages that have not changed are skipped, so it costs only what changed. Needs `knowledge:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `knowledge_base_id` | path | string (uuid) | Yes | | | `crawl_id` | path | string (uuid) | Yes | | ## Answer `202` with [KnowledgeCrawl](/reference/objects/KnowledgeCrawl). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A test key, or a key limited to some agents. | | `404` | This key reaches no such website. | | `409` | It is being read right now, or the project is frozen. | | `422` | Validation Error | | `429` | Too many knowledge requests just now. Wait for `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Read a website again. Pages that have not changed are skipped. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls/8a0c2e4f-6b8d-4f0a-c2e4-6a8c0e2a4c6e/refresh" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read a website again. Pages that have not changed are skipped. const response = await fetch("https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls/8a0c2e4f-6b8d-4f0a-c2e4-6a8c0e2a4c6e/refresh", { method: "POST", 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 # Read a website again. Pages that have not changed are skipped. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls/8a0c2e4f-6b8d-4f0a-c2e4-6a8c0e2a4c6e/refresh", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, timeout=60, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read a website again. Pages that have not changed are skipped. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls/8a0c2e4f-6b8d-4f0a-c2e4-6a8c0e2a4c6e/refresh", 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 // Read a website again. Pages that have not changed are skipped. 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/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls/8a0c2e4f-6b8d-4f0a-c2e4-6a8c0e2a4c6e/refresh")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("POST", 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 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 // Read a website again. Pages that have not changed are skipped. 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.Post, "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/crawls/8a0c2e4f-6b8d-4f0a-c2e4-6a8c0e2a4c6e/refresh") { }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => "", ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # List a knowledge base's sources > GET /v1/knowledge-bases/{knowledge_base_id}/documents Every source in a knowledge base — your files, the pages of a website it read, and its topics — newest first, each with where it is in indexing. Filter by `status`. Needs `knowledge:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `knowledge_base_id` | path | string (uuid) | Yes | | | `status` | query | [KnowledgeDocumentStatus](/reference/objects/KnowledgeDocumentStatus) or null | No | Only sources in this state. | | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [KnowledgeDocumentList](/reference/objects/KnowledgeDocumentList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such knowledge base. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # List what a knowledge base holds curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents?status=failed" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List what a knowledge base holds const response = await fetch("https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents?status=failed", { 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 # List what a knowledge base holds # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "status": "failed", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List what a knowledge base holds package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents?status=failed", 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 // List what a knowledge base holds 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/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents?status=failed")) .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 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 // List what a knowledge base holds 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/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents?status=failed") { }; 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 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"; ``` --- # Add a file to a knowledge base > POST /v1/knowledge-bases/{knowledge_base_id}/documents Send one file as `multipart/form-data`: text, Markdown, CSV, JSON, PDF or Word. The answer is `202` with the source, `pending`: it is indexed in the background, and agents answer from it once it reads `indexed`. The same bytes twice in one base are refused. Needs `knowledge:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `knowledge_base_id` | path | string (uuid) | Yes | | ## Body Sent as `multipart/form-data`. | Field | Type | Required | Description | |---|---|---|---| | `file` | string | Yes | The file. | | `generate_faqs` | boolean | No | Also write questions and answers from it. Each one costs credit. | ## Answer `202` with [KnowledgeDocument](/reference/objects/KnowledgeDocument). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A test key, or a key limited to some agents. | | `404` | This key reaches no such knowledge base. | | `409` | The same file is already in the base, or the project is frozen. | | `413` | The file is over the size this deployment takes. | | `415` | Not a file type the base reads, or a text file that is not UTF-8. | | `422` | The file is empty, or the base holds as many sources as it may. | | `429` | Too many files sent just now. Wait for `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Add a file to a knowledge base. With a live key. It is indexed in the background: read it until it says indexed. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ -F "file=@opening-hours.md;type=text/markdown" ``` **JavaScript** ```js import { readFile } from "node:fs/promises"; // Add a file to a knowledge base. With a live key. It is indexed in the background: read it until it says indexed. const form = new FormData(); form.append("file", new Blob([await readFile("opening-hours.md")], { type: "text/markdown" }), "opening-hours.md"); const response = await fetch("https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, }, body: form, }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Add a file to a knowledge base. With a live key. It is indexed in the background: read it until it says indexed. # pip install httpx import os import httpx with open("opening-hours.md", "rb") as upload: response = httpx.post( "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, files={"file": ("opening-hours.md", upload, "text/markdown")}, timeout=60, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Add a file to a knowledge base. With a live key. It is indexed in the background: read it until it says indexed. package main import ( "bytes" "fmt" "io" "mime/multipart" "net/http" "os" ) func main() { var form bytes.Buffer writer := multipart.NewWriter(&form) part, _ := writer.CreateFormFile("file", "opening-hours.md") contents, err := os.ReadFile("opening-hours.md") if err != nil { panic(err) } part.Write(contents) writer.Close() request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents", &form) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", writer.FormDataContentType()) 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 // Add a file to a knowledge base. With a live key. It is indexed in the background: read it until it says indexed. import java.io.ByteArrayOutputStream; import java.nio.file.Files; import java.nio.file.Path; 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 { String boundary = Long.toHexString(System.nanoTime()); ByteArrayOutputStream form = new ByteArrayOutputStream(); form.write(("--" + boundary + "\r\nContent-Disposition: form-data; name=\"file\"; filename=\"opening-hours.md\"\r\n" + "Content-Type: text/markdown\r\n\r\n").getBytes()); form.write(Files.readAllBytes(Path.of("opening-hours.md"))); form.write(("\r\n--" + boundary + "--\r\n").getBytes()); HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "multipart/form-data; boundary=" + boundary) .method("POST", HttpRequest.BodyPublishers.ofByteArray(form.toByteArray())) .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 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 // Add a file to a knowledge base. With a live key. It is indexed in the background: read it until it says indexed. using System.Net.Http.Headers; using System.Text; var form = new MultipartFormDataContent(); var upload = new ByteArrayContent(File.ReadAllBytes("opening-hours.md")); upload.Headers.ContentType = new MediaTypeHeaderValue("text/markdown"); form.Add(upload, "file", "opening-hours.md"); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("AIGENTLY_API_KEY")); var request = new HttpRequestMessage(HttpMethod.Post, "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents") { Content = form, }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => [ "file" => new CURLFile("opening-hours.md", "text/markdown"), ], ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Get a source > GET /v1/knowledge-bases/{knowledge_base_id}/documents/{document_id} One source, and where it is in indexing — read it again until it says `indexed` or `failed`. Needs `knowledge:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `knowledge_base_id` | path | string (uuid) | Yes | | | `document_id` | path | string (uuid) | Yes | | ## Answer `200` with [KnowledgeDocument](/reference/objects/KnowledgeDocument). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such source. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Read a source's indexing status curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read a source's indexing status const response = await fetch("https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d", { 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 # Read a source's indexing status # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read a source's indexing status package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d", 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 // Read a source's indexing status 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/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d")) .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 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 // Read a source's indexing status 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/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d") { }; 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 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"; ``` --- # Replace a file > PUT /v1/knowledge-bases/{knowledge_base_id}/documents/{document_id} Send a new version of a file, as `multipart/form-data`. It keeps its id and goes back to `pending`; agents keep answering from the old version until the new one is indexed — and if that fails, the old one stays, and `error` says why. Needs `knowledge:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `knowledge_base_id` | path | string (uuid) | Yes | | | `document_id` | path | string (uuid) | Yes | | ## Body Sent as `multipart/form-data`. | Field | Type | Required | Description | |---|---|---|---| | `file` | string | Yes | The new version. | ## Answer `202` with [KnowledgeDocument](/reference/objects/KnowledgeDocument). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A test key, or a key limited to some agents. | | `404` | This key reaches no such knowledge base. | | `409` | The source is being indexed right now, came from a website rather than a file, the same bytes are another source in the base, or the project is frozen. | | `413` | The file is over the size this deployment takes. | | `415` | Not a file type the base reads, or a text file that is not UTF-8. | | `422` | The file is empty, or the base holds as many sources as it may. | | `429` | Too many files sent just now. Wait for `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Replace a file with a new version. It keeps its id; agents answer from the old version until the new one is indexed. curl -sS --fail-with-body -X PUT "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ -F "file=@opening-hours.md;type=text/markdown" ``` **JavaScript** ```js import { readFile } from "node:fs/promises"; // Replace a file with a new version. It keeps its id; agents answer from the old version until the new one is indexed. const form = new FormData(); form.append("file", new Blob([await readFile("opening-hours.md")], { type: "text/markdown" }), "opening-hours.md"); const response = await fetch("https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d", { method: "PUT", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, }, body: form, }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Replace a file with a new version. It keeps its id; agents answer from the old version until the new one is indexed. # pip install httpx import os import httpx with open("opening-hours.md", "rb") as upload: response = httpx.put( "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, files={"file": ("opening-hours.md", upload, "text/markdown")}, timeout=60, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Replace a file with a new version. It keeps its id; agents answer from the old version until the new one is indexed. package main import ( "bytes" "fmt" "io" "mime/multipart" "net/http" "os" ) func main() { var form bytes.Buffer writer := multipart.NewWriter(&form) part, _ := writer.CreateFormFile("file", "opening-hours.md") contents, err := os.ReadFile("opening-hours.md") if err != nil { panic(err) } part.Write(contents) writer.Close() request, err := http.NewRequest("PUT", "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d", &form) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", writer.FormDataContentType()) 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 // Replace a file with a new version. It keeps its id; agents answer from the old version until the new one is indexed. import java.io.ByteArrayOutputStream; import java.nio.file.Files; import java.nio.file.Path; 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 { String boundary = Long.toHexString(System.nanoTime()); ByteArrayOutputStream form = new ByteArrayOutputStream(); form.write(("--" + boundary + "\r\nContent-Disposition: form-data; name=\"file\"; filename=\"opening-hours.md\"\r\n" + "Content-Type: text/markdown\r\n\r\n").getBytes()); form.write(Files.readAllBytes(Path.of("opening-hours.md"))); form.write(("\r\n--" + boundary + "--\r\n").getBytes()); HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "multipart/form-data; boundary=" + boundary) .method("PUT", HttpRequest.BodyPublishers.ofByteArray(form.toByteArray())) .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 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 // Replace a file with a new version. It keeps its id; agents answer from the old version until the new one is indexed. using System.Net.Http.Headers; using System.Text; var form = new MultipartFormDataContent(); var upload = new ByteArrayContent(File.ReadAllBytes("opening-hours.md")); upload.Headers.ContentType = new MediaTypeHeaderValue("text/markdown"); form.Add(upload, "file", "opening-hours.md"); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("AIGENTLY_API_KEY")); var request = new HttpRequestMessage(HttpMethod.Put, "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d") { Content = form, }; 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 "PUT", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => [ "file" => new CURLFile("opening-hours.md", "text/markdown"), ], ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Delete a source > DELETE /v1/knowledge-bases/{knowledge_base_id}/documents/{document_id} Remove a source and everything indexed from it. Agents stop answering from it on their next turn. Needs `knowledge:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `knowledge_base_id` | path | string (uuid) | Yes | | | `document_id` | path | string (uuid) | Yes | | ## Answer `200` with [KnowledgeDocumentDeleted](/reference/objects/KnowledgeDocumentDeleted). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A test key, or a key limited to some agents. | | `404` | This key reaches no such source. | | `409` | The project is frozen. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Delete a source curl -sS --fail-with-body -X DELETE "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Delete a source const response = await fetch("https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d", { method: "DELETE", 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 # Delete a source # pip install httpx import os import httpx response = httpx.delete( "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Delete a source package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("DELETE", "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d", 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 // Delete a source 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/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("DELETE", 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 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 // Delete a source 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.Delete, "https://api.aigently.ai/v1/knowledge-bases/6e8a0c2d-4f6b-4d8e-a0c2-4e6a8c0e2a4c/documents/7f9b1d3e-5a7c-4e9f-b1d3-5f7b9d1f3b5d") { }; 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 "DELETE", 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"; ``` --- # List MCP servers > GET /v1/mcp-servers The MCP servers in the projects this key reaches, oldest first. Needs `tools:write`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `project_id` | query | string (uuid) or null | No | Only this project's. | | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [McpServerList](/reference/objects/McpServerList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # List MCP servers curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/mcp-servers" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List MCP servers const response = await fetch("https://api.aigently.ai/v1/mcp-servers", { 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 # List MCP servers # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/mcp-servers", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List MCP servers package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/mcp-servers", 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 // List MCP servers 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/mcp-servers")) .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 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 // List MCP servers 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/mcp-servers") { }; 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 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"; ``` --- # Add an MCP server > POST /v1/mcp-servers A remote MCP server whose tools agents in the project can be given, by name in their definitions. The same address and credential rules as a tool. Needs `tools:write` and a live key. ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `allowed_tools` | array of string or null | No | | | `auth_key_id` | string (uuid) or null | No | A tool credential from the vault, assigned to the project. | | `name` | string | Yes | snake_case: it prefixes every tool name from it. | | `project_id` | string (uuid) | Yes | The project it belongs to. | | `timeout_ms` | integer | No | | | `url` | string | Yes | | ## Answer `201` with [McpServerObject](/reference/objects/McpServerObject). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A credential sent somewhere it does not go yet, or a test key. | | `409` | The project already has a server by that name, or it is frozen. | | `422` | Its address or its credential will not do. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | | `501` | This deployment does not run MCP servers. | ## Examples **curl** ```sh #!/bin/sh # Add an MCP server. With a live key. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/mcp-servers" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "name": "orders", "url": "https://orders.aigently.ai/mcp", "auth_key_id": "2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca", "allowed_tools": [ "lookup_order", "cancel_order" ] }' ``` **JavaScript** ```js // Add an MCP server. With a live key. const response = await fetch("https://api.aigently.ai/v1/mcp-servers", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "name": "orders", "url": "https://orders.aigently.ai/mcp", "auth_key_id": "2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca", "allowed_tools": [ "lookup_order", "cancel_order" ] }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Add an MCP server. With a live key. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/mcp-servers", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "name": "orders", "url": "https://orders.aigently.ai/mcp", "auth_key_id": "2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca", "allowed_tools": ["lookup_order", "cancel_order"], }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Add an MCP server. With a live key. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "name": "orders", "url": "https://orders.aigently.ai/mcp", "auth_key_id": "2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca", "allowed_tools": [ "lookup_order", "cancel_order" ] }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/mcp-servers", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Add an MCP server. With a live 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 { String body = """ { "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "name": "orders", "url": "https://orders.aigently.ai/mcp", "auth_key_id": "2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca", "allowed_tools": [ "lookup_order", "cancel_order" ] } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/mcp-servers")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Add an MCP server. With a live 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.Post, "https://api.aigently.ai/v1/mcp-servers") { Content = new StringContent( """ { "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "name": "orders", "url": "https://orders.aigently.ai/mcp", "auth_key_id": "2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca", "allowed_tools": [ "lookup_order", "cancel_order" ] } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "project_id" => "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "name" => "orders", "url" => "https://orders.aigently.ai/mcp", "auth_key_id" => "2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca", "allowed_tools" => ["lookup_order", "cancel_order"], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Get an MCP server > GET /v1/mcp-servers/{server_id} One MCP server, its path and query hidden. Needs `tools:write`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `server_id` | path | string (uuid) | Yes | | ## Answer `200` with [McpServerObject](/reference/objects/McpServerObject). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such server. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Read an MCP server curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/mcp-servers/1d3f5b7d-9f1b-4d3f-c5b7-d9f1b3d5f7b9" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read an MCP server const response = await fetch("https://api.aigently.ai/v1/mcp-servers/1d3f5b7d-9f1b-4d3f-c5b7-d9f1b3d5f7b9", { 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 # Read an MCP server # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/mcp-servers/1d3f5b7d-9f1b-4d3f-c5b7-d9f1b3d5f7b9", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read an MCP server package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/mcp-servers/1d3f5b7d-9f1b-4d3f-c5b7-d9f1b3d5f7b9", 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 // Read an MCP server 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/mcp-servers/1d3f5b7d-9f1b-4d3f-c5b7-d9f1b3d5f7b9")) .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 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 // Read an MCP server 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/mcp-servers/1d3f5b7d-9f1b-4d3f-c5b7-d9f1b3d5f7b9") { }; 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 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"; ``` --- # Change an MCP server > PATCH /v1/mcp-servers/{server_id} Send only what changes; a `url` still reading `••••` as it was read keeps what is stored. Needs `tools:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `server_id` | path | string (uuid) | Yes | | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `allowed_tools` | array of string or null | No | | | `auth_key_id` | string (uuid) or null | No | | | `name` | string or null | No | | | `timeout_ms` | integer or null | No | | | `url` | string or null | No | | ## Answer `200` with [McpServerObject](/reference/objects/McpServerObject). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A credential sent somewhere it does not go yet, or a test key. | | `404` | This key reaches no such server. | | `409` | The project already has a server by that name, or it is frozen. | | `422` | Its address or its credential will not do. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Change an MCP server. With a live key. curl -sS --fail-with-body -X PATCH "https://api.aigently.ai/v1/mcp-servers/1d3f5b7d-9f1b-4d3f-c5b7-d9f1b3d5f7b9" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "timeout_ms": 12000 }' ``` **JavaScript** ```js // Change an MCP server. With a live key. const response = await fetch("https://api.aigently.ai/v1/mcp-servers/1d3f5b7d-9f1b-4d3f-c5b7-d9f1b3d5f7b9", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "timeout_ms": 12000 }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Change an MCP server. With a live key. # pip install httpx import os import httpx response = httpx.patch( "https://api.aigently.ai/v1/mcp-servers/1d3f5b7d-9f1b-4d3f-c5b7-d9f1b3d5f7b9", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "timeout_ms": 12000, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Change an MCP server. With a live key. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "timeout_ms": 12000 }`) request, err := http.NewRequest("PATCH", "https://api.aigently.ai/v1/mcp-servers/1d3f5b7d-9f1b-4d3f-c5b7-d9f1b3d5f7b9", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Change an MCP server. With a live 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 { String body = """ { "timeout_ms": 12000 } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/mcp-servers/1d3f5b7d-9f1b-4d3f-c5b7-d9f1b3d5f7b9")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("PATCH", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Change an MCP server. With a live 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.Patch, "https://api.aigently.ai/v1/mcp-servers/1d3f5b7d-9f1b-4d3f-c5b7-d9f1b3d5f7b9") { Content = new StringContent( """ { "timeout_ms": 12000 } """, Encoding.UTF8, "application/json"), }; 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 "PATCH", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "timeout_ms" => 12000, ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Delete an MCP server > DELETE /v1/mcp-servers/{server_id} Agents stop being offered its tools on their next turn. Needs `tools:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `server_id` | path | string (uuid) | Yes | | ## Answer `200` with [Removed](/reference/objects/Removed). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such server. | | `409` | The project is frozen. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Delete an MCP server. With a live key. curl -sS --fail-with-body -X DELETE "https://api.aigently.ai/v1/mcp-servers/1d3f5b7d-9f1b-4d3f-c5b7-d9f1b3d5f7b9" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Delete an MCP server. With a live key. const response = await fetch("https://api.aigently.ai/v1/mcp-servers/1d3f5b7d-9f1b-4d3f-c5b7-d9f1b3d5f7b9", { method: "DELETE", 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 # Delete an MCP server. With a live key. # pip install httpx import os import httpx response = httpx.delete( "https://api.aigently.ai/v1/mcp-servers/1d3f5b7d-9f1b-4d3f-c5b7-d9f1b3d5f7b9", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Delete an MCP server. With a live key. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("DELETE", "https://api.aigently.ai/v1/mcp-servers/1d3f5b7d-9f1b-4d3f-c5b7-d9f1b3d5f7b9", 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 // Delete an MCP server. With a live 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/mcp-servers/1d3f5b7d-9f1b-4d3f-c5b7-d9f1b3d5f7b9")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("DELETE", 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 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 // Delete an MCP server. With a live 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.Delete, "https://api.aigently.ai/v1/mcp-servers/1d3f5b7d-9f1b-4d3f-c5b7-d9f1b3d5f7b9") { }; 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 "DELETE", 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"; ``` --- # List tools > GET /v1/tools The tools in the projects this key reaches, oldest first. Needs `tools:write`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `project_id` | query | string (uuid) or null | No | Only this project's. | | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [ToolList](/reference/objects/ToolList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # List tools curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/tools?project_id=0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List tools const response = await fetch("https://api.aigently.ai/v1/tools?project_id=0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", { 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 # List tools # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/tools", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List tools package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/tools?project_id=0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", 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 // List tools 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/tools?project_id=0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e")) .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 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 // List tools 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/tools?project_id=0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e") { }; 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 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"; ``` --- # Create a tool > POST /v1/tools A request an agent can make mid-conversation, in a project. Attach it to agents by name in their definitions. Its address may not be on this deployment's network, and a credential it names must be a tool credential assigned to the project — sent only where it already goes, or pinned there if this is its first use. Needs `tools:write` and a live key. ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `description` | string | Yes | | | `http` | object | Yes | `method`, `url`, `headers`, `auth` — `{"type": "bearer", "vault_key_id": …}` names a credential from `POST /v1/vault/secrets` — and `timeout_ms`. | | `name` | string | Yes | What the model calls it: letters, digits and underscores. | | `parameters` | object | Yes | The JSON Schema of what the model sends it. | | `project_id` | string (uuid) | Yes | The project it belongs to. | | `speaking_hint` | string | No | | ## Answer `201` with [ToolObject](/reference/objects/ToolObject). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A credential sent somewhere it does not go yet, or a test key. | | `409` | The project already has a tool by that name, or it is frozen. | | `422` | The tool's shape, its address or its credential will not do. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Create a tool. Give it to agents by name in their definitions. With a live key. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/tools" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "name": "lookup_order", "description": "Look up the status of an order by its number.", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "The order number." } }, "required": [ "order_id" ] }, "http": { "method": "GET", "url": "https://orders.aigently.ai/v1/orders/{order_id}", "auth": { "type": "bearer", "vault_key_id": "2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca" } }, "speaking_hint": "One moment while I look that up." }' ``` **JavaScript** ```js // Create a tool. Give it to agents by name in their definitions. With a live key. const response = await fetch("https://api.aigently.ai/v1/tools", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "name": "lookup_order", "description": "Look up the status of an order by its number.", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "The order number." } }, "required": [ "order_id" ] }, "http": { "method": "GET", "url": "https://orders.aigently.ai/v1/orders/{order_id}", "auth": { "type": "bearer", "vault_key_id": "2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca" } }, "speaking_hint": "One moment while I look that up." }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Create a tool. Give it to agents by name in their definitions. With a live key. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/tools", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "name": "lookup_order", "description": "Look up the status of an order by its number.", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "The order number.", }, }, "required": ["order_id"], }, "http": { "method": "GET", "url": "https://orders.aigently.ai/v1/orders/{order_id}", "auth": { "type": "bearer", "vault_key_id": "2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca", }, }, "speaking_hint": "One moment while I look that up.", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Create a tool. Give it to agents by name in their definitions. With a live key. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "name": "lookup_order", "description": "Look up the status of an order by its number.", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "The order number." } }, "required": [ "order_id" ] }, "http": { "method": "GET", "url": "https://orders.aigently.ai/v1/orders/{order_id}", "auth": { "type": "bearer", "vault_key_id": "2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca" } }, "speaking_hint": "One moment while I look that up." }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/tools", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Create a tool. Give it to agents by name in their definitions. With a live 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 { String body = """ { "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "name": "lookup_order", "description": "Look up the status of an order by its number.", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "The order number." } }, "required": [ "order_id" ] }, "http": { "method": "GET", "url": "https://orders.aigently.ai/v1/orders/{order_id}", "auth": { "type": "bearer", "vault_key_id": "2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca" } }, "speaking_hint": "One moment while I look that up." } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/tools")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Create a tool. Give it to agents by name in their definitions. With a live 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.Post, "https://api.aigently.ai/v1/tools") { Content = new StringContent( """ { "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "name": "lookup_order", "description": "Look up the status of an order by its number.", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "The order number." } }, "required": [ "order_id" ] }, "http": { "method": "GET", "url": "https://orders.aigently.ai/v1/orders/{order_id}", "auth": { "type": "bearer", "vault_key_id": "2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca" } }, "speaking_hint": "One moment while I look that up." } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "project_id" => "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "name" => "lookup_order", "description" => "Look up the status of an order by its number.", "parameters" => [ "type" => "object", "properties" => [ "order_id" => [ "type" => "string", "description" => "The order number.", ], ], "required" => ["order_id"], ], "http" => [ "method" => "GET", "url" => "https://orders.aigently.ai/v1/orders/{order_id}", "auth" => [ "type" => "bearer", "vault_key_id" => "2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca", ], ], "speaking_hint" => "One moment while I look that up.", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Get a tool > GET /v1/tools/{tool_id} One tool, its header values hidden. Needs `tools:write`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `tool_id` | path | string (uuid) | Yes | | ## Answer `200` with [ToolObject](/reference/objects/ToolObject). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such tool. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Read a tool curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/tools/0c2e4a6c-8e0a-4c2e-b4a6-c8e0a2c4e6a8" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read a tool const response = await fetch("https://api.aigently.ai/v1/tools/0c2e4a6c-8e0a-4c2e-b4a6-c8e0a2c4e6a8", { 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 # Read a tool # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/tools/0c2e4a6c-8e0a-4c2e-b4a6-c8e0a2c4e6a8", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read a tool package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/tools/0c2e4a6c-8e0a-4c2e-b4a6-c8e0a2c4e6a8", 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 // Read a tool 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/tools/0c2e4a6c-8e0a-4c2e-b4a6-c8e0a2c4e6a8")) .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 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 // Read a tool 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/tools/0c2e4a6c-8e0a-4c2e-b4a6-c8e0a2c4e6a8") { }; 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 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"; ``` --- # Change a tool > PATCH /v1/tools/{tool_id} Change what the model is told about a tool or the request it makes. Every agent that carries it uses the change on its next turn. Send `http` whole; a value still reading `••••` as it was read keeps what is stored. Needs `tools:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `tool_id` | path | string (uuid) | Yes | | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `description` | string or null | No | | | `http` | object or null | No | The whole request again. A value still reading `••••` as it was read keeps what is stored. | | `name` | string or null | No | | | `parameters` | object or null | No | | | `speaking_hint` | string or null | No | | ## Answer `200` with [ToolObject](/reference/objects/ToolObject). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A credential sent somewhere it does not go yet, or a test key. | | `404` | This key reaches no such tool. | | `409` | The project already has a tool by that name, or it is frozen. | | `422` | The tool's shape, its address or its credential will not do. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Change a tool. Every agent that has it uses the change on its next turn. With a live key. curl -sS --fail-with-body -X PATCH "https://api.aigently.ai/v1/tools/0c2e4a6c-8e0a-4c2e-b4a6-c8e0a2c4e6a8" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "description": "Look up where an order is, by its number." }' ``` **JavaScript** ```js // Change a tool. Every agent that has it uses the change on its next turn. With a live key. const response = await fetch("https://api.aigently.ai/v1/tools/0c2e4a6c-8e0a-4c2e-b4a6-c8e0a2c4e6a8", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "description": "Look up where an order is, by its number." }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Change a tool. Every agent that has it uses the change on its next turn. With a live key. # pip install httpx import os import httpx response = httpx.patch( "https://api.aigently.ai/v1/tools/0c2e4a6c-8e0a-4c2e-b4a6-c8e0a2c4e6a8", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "description": "Look up where an order is, by its number.", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Change a tool. Every agent that has it uses the change on its next turn. With a live key. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "description": "Look up where an order is, by its number." }`) request, err := http.NewRequest("PATCH", "https://api.aigently.ai/v1/tools/0c2e4a6c-8e0a-4c2e-b4a6-c8e0a2c4e6a8", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Change a tool. Every agent that has it uses the change on its next turn. With a live 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 { String body = """ { "description": "Look up where an order is, by its number." } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/tools/0c2e4a6c-8e0a-4c2e-b4a6-c8e0a2c4e6a8")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("PATCH", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Change a tool. Every agent that has it uses the change on its next turn. With a live 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.Patch, "https://api.aigently.ai/v1/tools/0c2e4a6c-8e0a-4c2e-b4a6-c8e0a2c4e6a8") { Content = new StringContent( """ { "description": "Look up where an order is, by its number." } """, Encoding.UTF8, "application/json"), }; 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 "PATCH", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "description" => "Look up where an order is, by its number.", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Delete a tool > DELETE /v1/tools/{tool_id} Every agent that carries it stops being offered it on its next turn. Needs `tools:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `tool_id` | path | string (uuid) | Yes | | ## Answer `200` with [Removed](/reference/objects/Removed). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such tool. | | `409` | The project is frozen. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Delete a tool. With a live key. curl -sS --fail-with-body -X DELETE "https://api.aigently.ai/v1/tools/0c2e4a6c-8e0a-4c2e-b4a6-c8e0a2c4e6a8" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Delete a tool. With a live key. const response = await fetch("https://api.aigently.ai/v1/tools/0c2e4a6c-8e0a-4c2e-b4a6-c8e0a2c4e6a8", { method: "DELETE", 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 # Delete a tool. With a live key. # pip install httpx import os import httpx response = httpx.delete( "https://api.aigently.ai/v1/tools/0c2e4a6c-8e0a-4c2e-b4a6-c8e0a2c4e6a8", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Delete a tool. With a live key. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("DELETE", "https://api.aigently.ai/v1/tools/0c2e4a6c-8e0a-4c2e-b4a6-c8e0a2c4e6a8", 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 // Delete a tool. With a live 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/tools/0c2e4a6c-8e0a-4c2e-b4a6-c8e0a2c4e6a8")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("DELETE", 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 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 // Delete a tool. With a live 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.Delete, "https://api.aigently.ai/v1/tools/0c2e4a6c-8e0a-4c2e-b4a6-c8e0a2c4e6a8") { }; 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 "DELETE", 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"; ``` --- # List tool credentials > GET /v1/vault/secrets The organization's tool credentials, oldest first: their names, last four characters and where each may be used — never their values. Needs `vault:write` and a key that reaches every project. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [VaultSecretList](/reference/objects/VaultSecretList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # List tool credentials. Never their values. With a key that reaches every project. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/vault/secrets" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List tool credentials. Never their values. With a key that reaches every project. const response = await fetch("https://api.aigently.ai/v1/vault/secrets", { 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 # List tool credentials. Never their values. With a key that reaches every project. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/vault/secrets", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List tool credentials. Never their values. With a key that reaches every project. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/vault/secrets", 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 // List tool credentials. Never their values. With a key that reaches every project. 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/vault/secrets")) .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 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 // List tool credentials. Never their values. With a key that reaches every project. 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/vault/secrets") { }; 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 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"; ``` --- # Add a tool credential > POST /v1/vault/secrets Seal a credential into the vault for the projects named, whose tools and MCP servers may then send it. Its value is never sent back. Needs `vault:write` and a live key. ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `name` | string | Yes | | | `project_ids` | array of string (uuid) | No | The projects whose tools may send it. | | `provider` | string | No | | | `secret` | string | Yes | The value. Never sent back. | ## Answer `201` with [VaultSecretObject](/reference/objects/VaultSecretObject). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | A project named is not this organization's. | | `409` | The organization already has a credential by that name. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Add a tool credential. Read the value from your own secret store. Only an owner can make this key. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/vault/secrets" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "name": "Orders API", "provider": "Aigently Orders", "secret": "your-orders-api-token", "project_ids": [ "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e" ] }' ``` **JavaScript** ```js // Add a tool credential. Read the value from your own secret store. Only an owner can make this key. const response = await fetch("https://api.aigently.ai/v1/vault/secrets", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "name": "Orders API", "provider": "Aigently Orders", "secret": "your-orders-api-token", "project_ids": [ "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e" ] }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Add a tool credential. Read the value from your own secret store. Only an owner can make this key. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/vault/secrets", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "name": "Orders API", "provider": "Aigently Orders", "secret": "your-orders-api-token", "project_ids": ["0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e"], }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Add a tool credential. Read the value from your own secret store. Only an owner can make this key. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "name": "Orders API", "provider": "Aigently Orders", "secret": "your-orders-api-token", "project_ids": [ "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e" ] }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/vault/secrets", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Add a tool credential. Read the value from your own secret store. Only an owner can make this 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 { String body = """ { "name": "Orders API", "provider": "Aigently Orders", "secret": "your-orders-api-token", "project_ids": [ "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e" ] } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/vault/secrets")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Add a tool credential. Read the value from your own secret store. Only an owner can make this 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.Post, "https://api.aigently.ai/v1/vault/secrets") { Content = new StringContent( """ { "name": "Orders API", "provider": "Aigently Orders", "secret": "your-orders-api-token", "project_ids": [ "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e" ] } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "name" => "Orders API", "provider" => "Aigently Orders", "secret" => "your-orders-api-token", "project_ids" => ["0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e"], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Get a tool credential > GET /v1/vault/secrets/{secret_id} One tool credential: its name, last four characters and where it may be used — never its value. Needs `vault:write` and a key that reaches every project. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `secret_id` | path | string (uuid) | Yes | | ## Answer `200` with [VaultSecretObject](/reference/objects/VaultSecretObject). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such credential. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Read a tool credential. Never its value. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/vault/secrets/2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read a tool credential. Never its value. const response = await fetch("https://api.aigently.ai/v1/vault/secrets/2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca", { 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 # Read a tool credential. Never its value. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/vault/secrets/2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read a tool credential. Never its value. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/vault/secrets/2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca", 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 // Read a tool credential. Never its value. 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/vault/secrets/2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca")) .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 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 // Read a tool credential. Never its value. 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/vault/secrets/2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca") { }; 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 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"; ``` --- # Change a tool credential > PATCH /v1/vault/secrets/{secret_id} Send a new value, a new name or label, or the whole list of projects that may use it. A new value is used from the next request any tool makes. Needs `vault:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `secret_id` | path | string (uuid) | Yes | | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `name` | string or null | No | | | `project_ids` | array of string (uuid) or null | No | The whole list of projects again. | | `provider` | string or null | No | Your own label for whose it is. | | `secret` | string or null | No | A new value, replacing the old. | ## Answer `200` with [VaultSecretObject](/reference/objects/VaultSecretObject). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such credential, or a project named is not here. | | `409` | The credential is revoked, or another one has that name. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Rotate a tool credential. Tools send the new value from their next request. curl -sS --fail-with-body -X PATCH "https://api.aigently.ai/v1/vault/secrets/2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "secret": "your-new-orders-api-token" }' ``` **JavaScript** ```js // Rotate a tool credential. Tools send the new value from their next request. const response = await fetch("https://api.aigently.ai/v1/vault/secrets/2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "secret": "your-new-orders-api-token" }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Rotate a tool credential. Tools send the new value from their next request. # pip install httpx import os import httpx response = httpx.patch( "https://api.aigently.ai/v1/vault/secrets/2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "secret": "your-new-orders-api-token", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Rotate a tool credential. Tools send the new value from their next request. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "secret": "your-new-orders-api-token" }`) request, err := http.NewRequest("PATCH", "https://api.aigently.ai/v1/vault/secrets/2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Rotate a tool credential. Tools send the new value from their next request. 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 { String body = """ { "secret": "your-new-orders-api-token" } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/vault/secrets/2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("PATCH", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Rotate a tool credential. Tools send the new value from their next request. 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.Patch, "https://api.aigently.ai/v1/vault/secrets/2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca") { Content = new StringContent( """ { "secret": "your-new-orders-api-token" } """, Encoding.UTF8, "application/json"), }; 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 "PATCH", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "secret" => "your-new-orders-api-token", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Delete a tool credential > DELETE /v1/vault/secrets/{secret_id} Tools and MCP servers that send it have none from their next request, and say so. Needs `vault:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `secret_id` | path | string (uuid) | Yes | | ## Answer `200` with [Removed](/reference/objects/Removed). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such credential. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Delete a tool credential. Tools that send it stop working until they are given another. curl -sS --fail-with-body -X DELETE "https://api.aigently.ai/v1/vault/secrets/2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Delete a tool credential. Tools that send it stop working until they are given another. const response = await fetch("https://api.aigently.ai/v1/vault/secrets/2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca", { method: "DELETE", 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 # Delete a tool credential. Tools that send it stop working until they are given another. # pip install httpx import os import httpx response = httpx.delete( "https://api.aigently.ai/v1/vault/secrets/2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Delete a tool credential. Tools that send it stop working until they are given another. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("DELETE", "https://api.aigently.ai/v1/vault/secrets/2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca", 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 // Delete a tool credential. Tools that send it stop working until they are given another. 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/vault/secrets/2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("DELETE", 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 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 // Delete a tool credential. Tools that send it stop working until they are given another. 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.Delete, "https://api.aigently.ai/v1/vault/secrets/2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca") { }; 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 "DELETE", 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"; ``` --- # List the do-not-call list > GET /v1/do-not-call Every number your organization's agents will never ring, newest first. `number` asks whether one number is listed. Needs `do_not_call:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `number` | query | string or null | No | Only this number, if it is listed. | | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [DoNotCallList](/reference/objects/DoNotCallList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A key limited to some projects or agents. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Ask whether a number may be called. An empty list means it is not on it. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/do-not-call?number=+12025550188" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Ask whether a number may be called. An empty list means it is not on it. const response = await fetch("https://api.aigently.ai/v1/do-not-call?number=+12025550188", { 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 # Ask whether a number may be called. An empty list means it is not on it. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/do-not-call", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "number": "+12025550188", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Ask whether a number may be called. An empty list means it is not on it. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/do-not-call?number=+12025550188", 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 // Ask whether a number may be called. An empty list means it is not on it. 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/do-not-call?number=+12025550188")) .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 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 // Ask whether a number may be called. An empty list means it is not on it. 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/do-not-call?number=+12025550188") { }; 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 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"; ``` --- # Add a number to the do-not-call list > POST /v1/do-not-call From the next dial on, no agent rings it: a single call, a campaign's contact or a reminder to it is refused with `do_not_call`. Adding a listed number again answers `200` with the entry, taking the new `reason` if one is sent. Needs `do_not_call:write` and a live key. ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `number` | string | Yes | The number, in international form. Spaces, dashes and brackets are ignored. | | `reason` | string | No | Why, in your words. | ## Answer `200` with [DoNotCallEntry](/reference/objects/DoNotCallEntry). `201` with [DoNotCallEntry](/reference/objects/DoNotCallEntry). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A test key, or a key limited to some projects or agents: the list decides which real people are called. | | `422` | Not a phone number, or the list is full. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Add a number to the do-not-call list. With a live key: the list decides which real people are called. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/do-not-call" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "number": "+12025550188", "reason": "Asked not to be called again" }' ``` **JavaScript** ```js // Add a number to the do-not-call list. With a live key: the list decides which real people are called. const response = await fetch("https://api.aigently.ai/v1/do-not-call", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "number": "+12025550188", "reason": "Asked not to be called again" }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Add a number to the do-not-call list. With a live key: the list decides which real people are called. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/do-not-call", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "number": "+12025550188", "reason": "Asked not to be called again", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Add a number to the do-not-call list. With a live key: the list decides which real people are called. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "number": "+12025550188", "reason": "Asked not to be called again" }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/do-not-call", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Add a number to the do-not-call list. With a live key: the list decides which real people are called. 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 { String body = """ { "number": "+12025550188", "reason": "Asked not to be called again" } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/do-not-call")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Add a number to the do-not-call list. With a live key: the list decides which real people are called. 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.Post, "https://api.aigently.ai/v1/do-not-call") { Content = new StringContent( """ { "number": "+12025550188", "reason": "Asked not to be called again" } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "number" => "+12025550188", "reason" => "Asked not to be called again", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Take a number off the do-not-call list > DELETE /v1/do-not-call/{number} Its agents may ring it again from the next dial. Recorded in the audit log under the key: taking a number off is undoing somebody's request not to be called. Needs `do_not_call:write` and a live key. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `number` | path | string | Yes | | ## Answer `200` with [DoNotCallRemoved](/reference/objects/DoNotCallRemoved). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | A test key, or a key limited to some projects or agents: the list decides which real people are called. | | `404` | The number is not listed. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Take a number off the do-not-call list. With a live key. Recorded in the audit log under it. curl -sS --fail-with-body -X DELETE "https://api.aigently.ai/v1/do-not-call/+12025550188" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Take a number off the do-not-call list. With a live key. Recorded in the audit log under it. const response = await fetch("https://api.aigently.ai/v1/do-not-call/+12025550188", { method: "DELETE", 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 # Take a number off the do-not-call list. With a live key. Recorded in the audit log under it. # pip install httpx import os import httpx response = httpx.delete( "https://api.aigently.ai/v1/do-not-call/+12025550188", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Take a number off the do-not-call list. With a live key. Recorded in the audit log under it. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("DELETE", "https://api.aigently.ai/v1/do-not-call/+12025550188", 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 // Take a number off the do-not-call list. With a live key. Recorded in the audit log under it. 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/do-not-call/+12025550188")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("DELETE", 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 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 // Take a number off the do-not-call list. With a live key. Recorded in the audit log under it. 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.Delete, "https://api.aigently.ai/v1/do-not-call/+12025550188") { }; 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 "DELETE", 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"; ``` --- # Upload a picture > POST /v1/attachments Upload a picture to send with a chat message, as `multipart/form-data` with the `agent_id` and the `file`. Send its `id` in the message's `attachment_ids`. A picture nobody sends is deleted after six hours. Needs `chats:write`. ## Body Sent as `multipart/form-data`. | Field | Type | Required | Description | |---|---|---|---| | `agent_id` | string (uuid) | Yes | The agent the picture is for. | | `file` | string | Yes | A JPEG, PNG, WebP or GIF. | ## Answer `201` with [Attachment](/reference/objects/Attachment). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such agent. | | `409` | The project is frozen. | | `413` | The picture is larger than the agent accepts. | | `422` | The agent does not accept pictures, or the file is not one. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Upload a picture to send. Send the id it returns in a message's attachment_ids. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/attachments" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ -F "agent_id=3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f" \ -F "file=@photo.jpg;type=image/jpeg" ``` **JavaScript** ```js import { readFile } from "node:fs/promises"; // Upload a picture to send. Send the id it returns in a message's attachment_ids. const form = new FormData(); form.append("agent_id", "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f"); form.append("file", new Blob([await readFile("photo.jpg")], { type: "image/jpeg" }), "photo.jpg"); const response = await fetch("https://api.aigently.ai/v1/attachments", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, }, body: form, }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Upload a picture to send. Send the id it returns in a message's attachment_ids. # pip install httpx import os import httpx with open("photo.jpg", "rb") as upload: response = httpx.post( "https://api.aigently.ai/v1/attachments", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, data={ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", }, files={"file": ("photo.jpg", upload, "image/jpeg")}, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Upload a picture to send. Send the id it returns in a message's attachment_ids. package main import ( "bytes" "fmt" "io" "mime/multipart" "net/http" "os" ) func main() { var form bytes.Buffer writer := multipart.NewWriter(&form) writer.WriteField("agent_id", "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f") part, _ := writer.CreateFormFile("file", "photo.jpg") contents, err := os.ReadFile("photo.jpg") if err != nil { panic(err) } part.Write(contents) writer.Close() request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/attachments", &form) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", writer.FormDataContentType()) 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 // Upload a picture to send. Send the id it returns in a message's attachment_ids. import java.io.ByteArrayOutputStream; import java.nio.file.Files; import java.nio.file.Path; 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 { String boundary = Long.toHexString(System.nanoTime()); ByteArrayOutputStream form = new ByteArrayOutputStream(); form.write(("--" + boundary + "\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\n3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f\r\n--" + boundary + "\r\nContent-Disposition: form-data; name=\"file\"; filename=\"photo.jpg\"\r\n" + "Content-Type: image/jpeg\r\n\r\n").getBytes()); form.write(Files.readAllBytes(Path.of("photo.jpg"))); form.write(("\r\n--" + boundary + "--\r\n").getBytes()); HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/attachments")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "multipart/form-data; boundary=" + boundary) .method("POST", HttpRequest.BodyPublishers.ofByteArray(form.toByteArray())) .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 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 // Upload a picture to send. Send the id it returns in a message's attachment_ids. using System.Net.Http.Headers; using System.Text; var form = new MultipartFormDataContent(); form.Add(new StringContent("3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f"), "agent_id"); var upload = new ByteArrayContent(File.ReadAllBytes("photo.jpg")); upload.Headers.ContentType = new MediaTypeHeaderValue("image/jpeg"); form.Add(upload, "file", "photo.jpg"); using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("AIGENTLY_API_KEY")); var request = new HttpRequestMessage(HttpMethod.Post, "https://api.aigently.ai/v1/attachments") { Content = form, }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => [ "agent_id" => "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "file" => new CURLFile("photo.jpg", "image/jpeg"), ], ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Start a chat > POST /v1/chats Start a chat with one of your agents by sending its first message. Answers `201` with the first `chat.turn`: the agent's greeting in `opening`, and its reply. Send `stream: true` for the reply as server-sent events. Needs `chats:write`. An `Idempotency-Key` is optional: the same request again returns the same chat. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string | No | Your own id for this chat. Optional. | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `agent_id` | string (uuid) | Yes | The agent to chat with. | | `agent_version` | integer or null | No | Answer with this published version of the agent rather than what is live now — its number from `GET /v1/agents/{id}/versions`. Its values and languages are that version's, and every turn of the conversation keeps it. | | `attachment_ids` | array of string (uuid) | No | Pictures to send with it, from `POST /v1/attachments`. | | `external_id` | string or null | No | | | `language` | string or null | No | One of the agent's language versions, like `ar`. | | `message` | string | Yes | What the person wrote. | | `metadata` | object | No | Your own data, returned on every read and event. The agent never sees it. | | `stream` | boolean | No | Send the reply as it is written, as server-sent events. `Accept: text/event-stream` does the same. | | `variables` | object | No | Values for the agent's `{{placeholders}}`. See its `variables_schema`. | ## Answer `201` with [ChatTurn](/reference/objects/ChatTurn). With `stream: true`, the same answer arrives as server-sent events instead — see [Chat and streaming](/guides/chat). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `402` | The organization's credit is used up. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such agent. | | `409` | The agent is not published, its project is frozen, or the first message is still being answered. | | `422` | A field, a variable or the language does not fit. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Start a chat curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/chats" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ -H "Idempotency-Key: chat-20931" \ --json '{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "message": "Hello, I would like to book a table.", "variables": { "first_name": "Sara" } }' ``` **JavaScript** ```js // Start a chat const response = await fetch("https://api.aigently.ai/v1/chats", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "chat-20931", }, body: JSON.stringify({ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "message": "Hello, I would like to book a table.", "variables": { "first_name": "Sara" } }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Start a chat # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/chats", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", "Idempotency-Key": "chat-20931", }, json={ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "message": "Hello, I would like to book a table.", "variables": { "first_name": "Sara", }, }, timeout=60, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Start a chat package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "message": "Hello, I would like to book a table.", "variables": { "first_name": "Sara" } }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/chats", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") request.Header.Set("Idempotency-Key", "chat-20931") 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 // Start a chat 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 { String body = """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "message": "Hello, I would like to book a table.", "variables": { "first_name": "Sara" } } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/chats")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .header("Idempotency-Key", "chat-20931") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Start a chat 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.Post, "https://api.aigently.ai/v1/chats") { Content = new StringContent( """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "message": "Hello, I would like to book a table.", "variables": { "first_name": "Sara" } } """, Encoding.UTF8, "application/json"), }; request.Headers.Add("Idempotency-Key", "chat-20931"); 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", "Idempotency-Key: chat-20931", ], CURLOPT_POSTFIELDS => json_encode([ "agent_id" => "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "message" => "Hello, I would like to book a table.", "variables" => [ "first_name" => "Sara", ], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Send a message > POST /v1/conversations/{conversation_id}/messages Send the next message in a chat started through the API, and get the agent's reply as a `chat.turn` — or, with `stream: true`, as server-sent events. One message at a time: wait for the reply before sending the next. Needs `chats:write`. An `Idempotency-Key` is optional: the same message again returns the reply it already got. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `conversation_id` | path | string (uuid) | Yes | | | `Idempotency-Key` | header | string | No | Your own id for this message. Optional. | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `attachment_ids` | array of string (uuid) | No | Pictures to send with it, from `POST /v1/attachments`. | | `message` | string | Yes | What the person wrote. | | `stream` | boolean | No | Send the reply as it is written, as server-sent events. `Accept: text/event-stream` does the same. | ## Answer `200` with [ChatTurn](/reference/objects/ChatTurn). With `stream: true`, the same answer arrives as server-sent events instead — see [Chat and streaming](/guides/chat). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `402` | The organization's credit is used up. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such chat, or it was not started through the API. | | `409` | The chat has ended or reached its length, the agent is still answering the last message, or this is not a chat. | | `422` | The message, or its Idempotency-Key, does not fit. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Send the next message curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "message": "For four people, at seven." }' ``` **JavaScript** ```js // Send the next message const response = await fetch("https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "message": "For four people, at seven." }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Send the next message # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "message": "For four people, at seven.", }, timeout=60, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Send the next message package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "message": "For four people, at seven." }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Send the next message 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 { String body = """ { "message": "For four people, at seven." } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Send the next message 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.Post, "https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages") { Content = new StringContent( """ { "message": "For four people, at seven." } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "message" => "For four people, at seven.", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` **curl** ```sh #!/bin/sh # Stream the reply as it is written curl -sS --fail-with-body -N -X POST "https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "message": "Can I bring my dog?", "stream": true }' ``` **JavaScript** ```js // Stream the reply as it is written const response = await fetch("https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "message": "Can I bring my dog?", "stream": true }), }); if (!response.ok) { const problem = await response.json(); throw new Error(`${problem.code}: ${problem.detail}`); } // Each event is an "event:" line, a "data:" line of JSON, and a blank line. const decoder = new TextDecoder(); let buffer = ""; for await (const chunk of response.body) { buffer += decoder.decode(chunk, { stream: true }); let end; while ((end = buffer.indexOf("\n\n")) >= 0) { const [eventLine, dataLine] = buffer.slice(0, end).split("\n"); buffer = buffer.slice(end + 2); const event = eventLine.slice("event: ".length); const data = JSON.parse(dataLine.slice("data: ".length)); if (event === "delta") process.stdout.write(data.text); if (event === "done") console.log("\n", data); if (event === "error") throw new Error(`${data.code}: ${data.detail}`); } } ``` **Python** ```python # Stream the reply as it is written # pip install httpx import json import os import httpx with httpx.stream( "POST", "https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "message": "Can I bring my dog?", "stream": True, }, timeout=60, ) as response: if response.is_error: raise SystemExit(response.read().decode()) # Each event is an "event:" line, a "data:" line of JSON, and a blank line. event = None for line in response.iter_lines(): if line.startswith("event: "): event = line.removeprefix("event: ") elif line.startswith("data: "): data = json.loads(line.removeprefix("data: ")) if event == "delta": print(data["text"], end="", flush=True) elif event == "done": print("\n", data) elif event == "error": raise SystemExit(f"{data['code']}: {data['detail']}") ``` **Go** ```go // Stream the reply as it is written package main import ( "bufio" "bytes" "encoding/json" "fmt" "io" "net/http" "os" "strings" ) func main() { payload := []byte(`{ "message": "Can I bring my dog?", "stream": true }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") response, err := http.DefaultClient.Do(request) if err != nil { panic(err) } defer response.Body.Close() if response.StatusCode >= 400 { body, _ := io.ReadAll(response.Body) fmt.Fprintln(os.Stderr, string(body)) os.Exit(1) } // Each event is an "event:" line, a "data:" line of JSON, and a blank line. scanner := bufio.NewScanner(response.Body) scanner.Buffer(make([]byte, 64*1024), 1024*1024) event := "" for scanner.Scan() { line := scanner.Text() if name, found := strings.CutPrefix(line, "event: "); found { event = name continue } data, found := strings.CutPrefix(line, "data: ") if !found { continue } switch event { case "delta": var delta struct { Text string `json:"text"` } json.Unmarshal([]byte(data), &delta) fmt.Print(delta.Text) case "done": fmt.Println("\n" + data) case "error": fmt.Fprintln(os.Stderr, data) os.Exit(1) } } } ``` **Java** ```java // Stream the reply as it is written import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.util.stream.Stream; public class Main { public static void main(String[] args) throws Exception { String body = """ { "message": "Can I bring my dog?", "stream": true } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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> response = client.send(request, HttpResponse.BodyHandlers.ofLines()); if (response.statusCode() >= 400) { response.body().forEach(System.err::println); System.exit(1); } // Each event is an "event:" line, a "data:" line of JSON, and a blank line. // Read each data line with your JSON library. response.body().filter(line -> !line.isEmpty()).forEach(System.out::println); } } ``` **C#** ```csharp // Stream the reply as it is written using System.Net.Http.Headers; using System.Text; using System.Text.Json; using var client = new HttpClient(); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("AIGENTLY_API_KEY")); var request = new HttpRequestMessage(HttpMethod.Post, "https://api.aigently.ai/v1/conversations/2e4a6c8d-0f1b-4d3e-a5c7-9e1b3d5f7a9c/messages") { Content = new StringContent( """ { "message": "Can I bring my dog?", "stream": true } """, Encoding.UTF8, "application/json"), }; using var response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead); if (!response.IsSuccessStatusCode) { Console.Error.WriteLine(await response.Content.ReadAsStringAsync()); return 1; } // Each event is an "event:" line, a "data:" line of JSON, and a blank line. using var reader = new StreamReader(await response.Content.ReadAsStreamAsync()); var eventName = ""; while (await reader.ReadLineAsync() is { } line) { if (line.StartsWith("event: ")) { eventName = line["event: ".Length..]; continue; } if (!line.StartsWith("data: ")) { continue; } var data = line["data: ".Length..]; if (eventName == "delta") { Console.Write(JsonDocument.Parse(data).RootElement.GetProperty("text").GetString()); } else if (eventName == "done") { Console.WriteLine("\n" + data); } else if (eventName == "error") { Console.Error.WriteLine(data); return 1; } } return 0; ``` **PHP** ```php true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "message" => "Can I bring my dog?", "stream" => true, ]), // Each event is an "event:" line, a "data:" line of JSON, and a blank line. CURLOPT_WRITEFUNCTION => function ($curl, $chunk) use (&$event, &$buffer, &$failed) { $buffer .= $chunk; while (($end = strpos($buffer, "\n")) !== false) { $line = substr($buffer, 0, $end); $buffer = substr($buffer, $end + 1); if (str_starts_with($line, "event: ")) { $event = substr($line, 7); } elseif (str_starts_with($line, "data: ")) { $data = substr($line, 6); if ($event === "delta") { echo json_decode($data, true)["text"]; } elseif ($event === "done") { echo "\n", $data, "\n"; } elseif ($event === "error") { fwrite(STDERR, $data . "\n"); $failed = true; } } } return strlen($chunk); }, ]); curl_exec($curl); if ($failed || curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $buffer . "\n"); exit(1); } ``` --- # Start a WhatsApp conversation > POST /v1/whatsapp/conversations Send a person an approved template from one of your WhatsApp numbers — an appointment reminder, a delivery notice — and the number's agent answers when they write back, with the template's words as its own first line and your `variables`. The conversation waits a day for an answer. A template Meta refuses ends the conversation `failed`, with Meta's reason in `error`. Needs `whatsapp:write`, a live key and an `Idempotency-Key`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string | Yes | Your own id for this message. Required. | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `external_id` | string or null | No | | | `metadata` | object | No | Your own data, returned on every read and event. The agent never sees it. | | `sender_id` | string (uuid) | Yes | The WhatsApp number to send from. | | `template` | [WhatsappTemplateChoice](/reference/objects/WhatsappTemplateChoice) | Yes | | | `to_number` | string | Yes | The person's WhatsApp number, in international format, like `+966501234567`. | | `variables` | object | No | Values for the agent's `{{placeholders}}`, for when the person answers. | ## Answer `201` with [Conversation](/reference/objects/Conversation). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `402` | The organization's credit is used up. | | `403` | A test key: there are no WhatsApp test numbers. | | `404` | This key reaches no such WhatsApp number. | | `409` | The person is on a block list, the number's agent is not published, or the connection is not ready. | | `422` | No such approved template, or the wrong number of values. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | | `501` | This deployment does not run WhatsApp. | ## Examples **curl** ```sh #!/bin/sh # Start a WhatsApp conversation. The agent answers when they write back. With a live key. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/whatsapp/conversations" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ -H "Idempotency-Key: reminder-4471" \ --json '{ "sender_id": "7d9f1b3d-5f7b-4d9f-c1b3-d5f7b9dbfd1f", "to_number": "+966501234567", "template": { "name": "appointment_reminder", "language": "en_US", "parameters": [ "Sara", "Monday at 10" ] }, "variables": { "first_name": "Sara" }, "metadata": { "booking": "4471" } }' ``` **JavaScript** ```js // Start a WhatsApp conversation. The agent answers when they write back. With a live key. const response = await fetch("https://api.aigently.ai/v1/whatsapp/conversations", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "reminder-4471", }, body: JSON.stringify({ "sender_id": "7d9f1b3d-5f7b-4d9f-c1b3-d5f7b9dbfd1f", "to_number": "+966501234567", "template": { "name": "appointment_reminder", "language": "en_US", "parameters": [ "Sara", "Monday at 10" ] }, "variables": { "first_name": "Sara" }, "metadata": { "booking": "4471" } }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Start a WhatsApp conversation. The agent answers when they write back. With a live key. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/whatsapp/conversations", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", "Idempotency-Key": "reminder-4471", }, json={ "sender_id": "7d9f1b3d-5f7b-4d9f-c1b3-d5f7b9dbfd1f", "to_number": "+966501234567", "template": { "name": "appointment_reminder", "language": "en_US", "parameters": ["Sara", "Monday at 10"], }, "variables": { "first_name": "Sara", }, "metadata": { "booking": "4471", }, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Start a WhatsApp conversation. The agent answers when they write back. With a live key. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "sender_id": "7d9f1b3d-5f7b-4d9f-c1b3-d5f7b9dbfd1f", "to_number": "+966501234567", "template": { "name": "appointment_reminder", "language": "en_US", "parameters": [ "Sara", "Monday at 10" ] }, "variables": { "first_name": "Sara" }, "metadata": { "booking": "4471" } }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/whatsapp/conversations", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") request.Header.Set("Idempotency-Key", "reminder-4471") 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 // Start a WhatsApp conversation. The agent answers when they write back. With a live 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 { String body = """ { "sender_id": "7d9f1b3d-5f7b-4d9f-c1b3-d5f7b9dbfd1f", "to_number": "+966501234567", "template": { "name": "appointment_reminder", "language": "en_US", "parameters": [ "Sara", "Monday at 10" ] }, "variables": { "first_name": "Sara" }, "metadata": { "booking": "4471" } } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/whatsapp/conversations")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .header("Idempotency-Key", "reminder-4471") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Start a WhatsApp conversation. The agent answers when they write back. With a live 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.Post, "https://api.aigently.ai/v1/whatsapp/conversations") { Content = new StringContent( """ { "sender_id": "7d9f1b3d-5f7b-4d9f-c1b3-d5f7b9dbfd1f", "to_number": "+966501234567", "template": { "name": "appointment_reminder", "language": "en_US", "parameters": [ "Sara", "Monday at 10" ] }, "variables": { "first_name": "Sara" }, "metadata": { "booking": "4471" } } """, Encoding.UTF8, "application/json"), }; request.Headers.Add("Idempotency-Key", "reminder-4471"); 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", "Idempotency-Key: reminder-4471", ], CURLOPT_POSTFIELDS => json_encode([ "sender_id" => "7d9f1b3d-5f7b-4d9f-c1b3-d5f7b9dbfd1f", "to_number" => "+966501234567", "template" => [ "name" => "appointment_reminder", "language" => "en_US", "parameters" => ["Sara", "Monday at 10"], ], "variables" => [ "first_name" => "Sara", ], "metadata" => [ "booking" => "4471", ], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # List WhatsApp numbers > GET /v1/whatsapp/senders The organization's WhatsApp numbers this key reaches, oldest first, each with the agent that answers it. Needs `whatsapp:write`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [WhatsappSenderList](/reference/objects/WhatsappSenderList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # List WhatsApp numbers curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/whatsapp/senders" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List WhatsApp numbers const response = await fetch("https://api.aigently.ai/v1/whatsapp/senders", { 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 # List WhatsApp numbers # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/whatsapp/senders", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List WhatsApp numbers package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/whatsapp/senders", 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 // List WhatsApp numbers 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/whatsapp/senders")) .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 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 // List WhatsApp numbers 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/whatsapp/senders") { }; 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 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"; ``` --- # List a WhatsApp number's templates > GET /v1/whatsapp/senders/{sender_id}/templates The message templates Meta has approved for this number's business account: the ones a conversation can be started with. Write and approve them in WhatsApp Manager. Needs `whatsapp:write`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `sender_id` | path | string (uuid) | Yes | | ## Answer `200` with [WhatsappTemplateList](/reference/objects/WhatsappTemplateList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such WhatsApp number. | | `409` | The connection has no business account id or access token. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | | `501` | This deployment does not run WhatsApp. | ## Examples **curl** ```sh #!/bin/sh # List a WhatsApp number's templates. Write and approve them in WhatsApp Manager. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/whatsapp/senders/7d9f1b3d-5f7b-4d9f-c1b3-d5f7b9dbfd1f/templates" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List a WhatsApp number's templates. Write and approve them in WhatsApp Manager. const response = await fetch("https://api.aigently.ai/v1/whatsapp/senders/7d9f1b3d-5f7b-4d9f-c1b3-d5f7b9dbfd1f/templates", { 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 # List a WhatsApp number's templates. Write and approve them in WhatsApp Manager. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/whatsapp/senders/7d9f1b3d-5f7b-4d9f-c1b3-d5f7b9dbfd1f/templates", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List a WhatsApp number's templates. Write and approve them in WhatsApp Manager. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/whatsapp/senders/7d9f1b3d-5f7b-4d9f-c1b3-d5f7b9dbfd1f/templates", 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 // List a WhatsApp number's templates. Write and approve them in WhatsApp Manager. 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/whatsapp/senders/7d9f1b3d-5f7b-4d9f-c1b3-d5f7b9dbfd1f/templates")) .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 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 // List a WhatsApp number's templates. Write and approve them in WhatsApp Manager. 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/whatsapp/senders/7d9f1b3d-5f7b-4d9f-c1b3-d5f7b9dbfd1f/templates") { }; 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 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"; ``` --- # Start a browser call > POST /v1/web-calls Start a voice conversation with an agent in your own web page. Call this from your server, with the agent's values and your own data, and give the page the answer's `url` and `token`: it joins with `@aigently/web`. The token joins this one call and lasts 15 minutes. Needs `calls:write` and a live key. An `Idempotency-Key` makes a retry return the same call. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `Idempotency-Key` | header | string | No | Your own id for this call, up to 120 characters. | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `agent_id` | string (uuid) | Yes | The agent to talk to. Browser voice must be on. | | `agent_version` | integer or null | No | Answer with this published version of the agent rather than what is live now — its number from `GET /v1/agents/{id}/versions`. Its values and languages are that version's, and every turn of the conversation keeps it. | | `external_id` | string or null | No | | | `language` | string or null | No | One of the agent's language versions, like `ar`. | | `metadata` | object | No | Your own data, returned on every read and event. The agent never sees it. | | `participant_name` | string or null | No | What the call names the person in the page. `Caller` unless you say. | | `variables` | object | No | Values for the agent's `{{placeholders}}`. See its `variables_schema`. | ## Answer `201` with [WebCall](/reference/objects/WebCall). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `402` | The organization's credit is used up. | | `403` | A test key: a browser call is a real conversation. | | `404` | This key reaches no such agent. | | `409` | The agent does not take browser calls or is not published, or its project is frozen. | | `422` | A field or a variable does not fit — or the `Idempotency-Key` was used for a different request. | | `429` | Too many calls going, or today's limit reached. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | | `501` | This deployment does not run voice. | | `502` | The voice service could not be reached. Try again shortly. | ## Examples **curl** ```sh #!/bin/sh # Start a browser call for your page. From your server, with a live key: give the page the url and token, and it joins with @aigently/web. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/web-calls" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ -H "Idempotency-Key: visit-20931" \ --json '{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables": { "first_name": "Sara" }, "metadata": { "session": "S-20931" } }' ``` **JavaScript** ```js // Start a browser call for your page. From your server, with a live key: give the page the url and token, and it joins with @aigently/web. const response = await fetch("https://api.aigently.ai/v1/web-calls", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "visit-20931", }, body: JSON.stringify({ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables": { "first_name": "Sara" }, "metadata": { "session": "S-20931" } }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Start a browser call for your page. From your server, with a live key: give the page the url and token, and it joins with @aigently/web. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/web-calls", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", "Idempotency-Key": "visit-20931", }, json={ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables": { "first_name": "Sara", }, "metadata": { "session": "S-20931", }, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Start a browser call for your page. From your server, with a live key: give the page the url and token, and it joins with @aigently/web. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables": { "first_name": "Sara" }, "metadata": { "session": "S-20931" } }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/web-calls", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") request.Header.Set("Idempotency-Key", "visit-20931") 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 // Start a browser call for your page. From your server, with a live key: give the page the url and token, and it joins with @aigently/web. 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 { String body = """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables": { "first_name": "Sara" }, "metadata": { "session": "S-20931" } } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/web-calls")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .header("Idempotency-Key", "visit-20931") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Start a browser call for your page. From your server, with a live key: give the page the url and token, and it joins with @aigently/web. 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.Post, "https://api.aigently.ai/v1/web-calls") { Content = new StringContent( """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables": { "first_name": "Sara" }, "metadata": { "session": "S-20931" } } """, Encoding.UTF8, "application/json"), }; request.Headers.Add("Idempotency-Key", "visit-20931"); 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", "Idempotency-Key: visit-20931", ], CURLOPT_POSTFIELDS => json_encode([ "agent_id" => "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "variables" => [ "first_name" => "Sara", ], "metadata" => [ "session" => "S-20931", ], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # List conversations > GET /v1/conversations Conversations this key can reach, newest first. Use `order=changed` with `changed_after` to sync: oldest change first, and the last page's `next_cursor` is the place to ask again from later. Changes from the last minute wait for the next page. With `q`, only conversations whose transcript has those words, each with the passage that matched — which also needs `transcripts:read`, 30 a minute per key. Needs `conversations:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `order` | query | [Order](/reference/objects/Order) | No | `newest`, `oldest` or `changed`. | | `agent_id` | query | string (uuid) or null | No | | | `project_id` | query | string (uuid) or null | No | | | `channel` | query | [Channel](/reference/objects/Channel) or null | No | | | `direction` | query | [Direction](/reference/objects/Direction) or null | No | | | `status` | query | array of [ConversationStatus](/reference/objects/ConversationStatus) or null | No | Repeat to ask for several. | | `disposition` | query | [Disposition](/reference/objects/Disposition) or null | No | | | `outcome` | query | [Outcome](/reference/objects/Outcome) or null | No | The analysis's outcome. | | `ended_by` | query | [EndedBy](/reference/objects/EndedBy) or null | No | | | `mode` | query | [ConversationMode](/reference/objects/ConversationMode) or null | No | | | `phone_number_id` | query | string (uuid) or null | No | | | `from_number` | query | string or null | No | | | `to_number` | query | string or null | No | | | `campaign_id` | query | string (uuid) or null | No | | | `external_id` | query | string or null | No | Your own id, as `POST /v1/calls` or `/v1/chats` sent it. | | `created_after` | query | string (date-time) or null | No | Started at or after this time. | | `created_before` | query | string (date-time) or null | No | Started before this time. | | `changed_after` | query | string (date-time) or null | No | Changed at or after this time. | | `changed_before` | query | string (date-time) or null | No | Changed before this time. | | `limit` | query | integer | No | How many to return, 1 to 100. | | `q` | query | string or null | No | Words that were said. A word also finds longer ones that start with it (`refund` finds `refunded`), a phrase in quotes is found as written, and `-word` leaves out the conversations that have it. Needs `transcripts:read`. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [ConversationList](/reference/objects/ConversationList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # List conversations curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations?agent_id=8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c&status=completed&limit=10" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List conversations const response = await fetch("https://api.aigently.ai/v1/conversations?agent_id=8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c&status=completed&limit=10", { 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 # List conversations # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "agent_id": "8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c", "status": "completed", "limit": 10, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List conversations package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations?agent_id=8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c&status=completed&limit=10", 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 // List conversations 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/conversations?agent_id=8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c&status=completed&limit=10")) .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 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 // List conversations 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/conversations?agent_id=8a1f3c2e-0b6d-4f5e-9a7c-2d4e6f8a0b1c&status=completed&limit=10") { }; 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 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"; ``` **curl** ```sh #!/bin/sh # Sync what changed. Send each page's next_cursor back as cursor= until has_more is false. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations?order=changed&changed_after=2026-10-01T00:00:00Z" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Sync what changed. Send each page's next_cursor back as cursor= until has_more is false. const response = await fetch("https://api.aigently.ai/v1/conversations?order=changed&changed_after=2026-10-01T00:00:00Z", { 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 # Sync what changed. Send each page's next_cursor back as cursor= until has_more is false. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "order": "changed", "changed_after": "2026-10-01T00:00:00Z", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Sync what changed. Send each page's next_cursor back as cursor= until has_more is false. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations?order=changed&changed_after=2026-10-01T00:00:00Z", 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 // Sync what changed. Send each page's next_cursor back as cursor= until has_more is false. 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/conversations?order=changed&changed_after=2026-10-01T00:00:00Z")) .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 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 // Sync what changed. Send each page's next_cursor back as cursor= until has_more is false. 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/conversations?order=changed&changed_after=2026-10-01T00:00:00Z") { }; 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 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"; ``` **curl** ```sh #!/bin/sh # Find conversations by what was said. Each one comes with the passage that matched. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations?q=refund&limit=10" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Find conversations by what was said. Each one comes with the passage that matched. const response = await fetch("https://api.aigently.ai/v1/conversations?q=refund&limit=10", { 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 # Find conversations by what was said. Each one comes with the passage that matched. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "q": "refund", "limit": 10, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Find conversations by what was said. Each one comes with the passage that matched. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations?q=refund&limit=10", 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 // Find conversations by what was said. Each one comes with the passage that matched. 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/conversations?q=refund&limit=10")) .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 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 // Find conversations by what was said. Each one comes with the passage that matched. 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/conversations?q=refund&limit=10") { }; 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 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"; ``` --- # List deleted conversations > GET /v1/conversations/deleted Conversations deleted in the last 30 days, oldest first — by retention, from the console, or with their agent or project. Remove them from your copy. Keep the last page's `next_cursor` and ask again later for what was deleted since. Needs `conversations:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `deleted_after` | query | string (date-time) or null | No | Deleted at or after this time. | | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [DeletedConversationList](/reference/objects/DeletedConversationList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # List deleted conversations curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/deleted" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List deleted conversations const response = await fetch("https://api.aigently.ai/v1/conversations/deleted", { 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 # List deleted conversations # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations/deleted", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List deleted conversations package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations/deleted", 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 // List deleted conversations 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/conversations/deleted")) .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 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 // List deleted conversations 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/conversations/deleted") { }; 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 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"; ``` --- # Get a conversation > GET /v1/conversations/{conversation_id} One conversation. Add `include=transcript` for what was said as well, which also needs `transcripts:read`. Add `include=cost` for what it cost, which needs `billing:read`. Needs `conversations:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `conversation_id` | path | string (uuid) | Yes | | | `include` | query | array of [Include](/reference/objects/Include) or null | No | `transcript`, `cost`. Repeatable. | ## Answer `200` with [ConversationWithTranscript](/reference/objects/ConversationWithTranscript). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such conversation. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Read a conversation with its transcript curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read a conversation with its transcript const response = await fetch("https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript", { 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 # Read a conversation with its transcript # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "include": "transcript", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read a conversation with its transcript package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript", 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 // Read a conversation with its transcript 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript")) .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 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 // Read a conversation with its transcript 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=transcript") { }; 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 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"; ``` **curl** ```sh #!/bin/sh # Read what a conversation cost curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=cost" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read what a conversation cost const response = await fetch("https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=cost", { 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 # Read what a conversation cost # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "include": "cost", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read what a conversation cost package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=cost", 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 // Read what a conversation cost 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=cost")) .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 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 // Read what a conversation cost 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d?include=cost") { }; 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 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"; ``` --- # Delete a conversation > DELETE /v1/conversations/{conversation_id} Delete a conversation, with its transcript, its recording and the pictures sent in it. A call still in progress is refused; an open chat is charged for what it has used, then deleted. It cannot be undone. It is listed under `GET /v1/conversations/deleted` and sent as `conversation.deleted`, so copies elsewhere can follow. Needs `conversations:delete`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `conversation_id` | path | string (uuid) | Yes | | ## Answer `200` with [Deleted](/reference/objects/Deleted). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such conversation. | | `409` | The call is still in progress, the agent is answering a message in the chat, or the project is frozen. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Delete a conversation. With its recording, for good. curl -sS --fail-with-body -X DELETE "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Delete a conversation. With its recording, for good. const response = await fetch("https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d", { method: "DELETE", 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 # Delete a conversation. With its recording, for good. # pip install httpx import os import httpx response = httpx.delete( "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Delete a conversation. With its recording, for good. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("DELETE", "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d", 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 // Delete a conversation. With its recording, for good. 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("DELETE", 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 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 // Delete a conversation. With its recording, for good. 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.Delete, "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d") { }; 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 "DELETE", 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"; ``` --- # Analyse a conversation again > POST /v1/conversations/{conversation_id}/analysis Run the agent's analysis on a conversation that has ended — again, or for the first time — with the agent's analysis settings as they are now. It costs credit, like any analysis, and an organization may ask 10 a minute. A test key's call gets its sample analysis again, at no cost; a test key's chat is analysed by the real model, and charged. Answers with the conversation and its new `analysis`. Needs `analysis:run`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `conversation_id` | path | string (uuid) | Yes | | ## Answer `200` with [ConversationWithTranscript](/reference/objects/ConversationWithTranscript). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `402` | The organization's credit is used up. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such conversation. | | `409` | The conversation is still in progress, or its project is frozen. | | `422` | The conversation is too short to analyse. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | | `502` | The model did not answer. Try again shortly. | ## Examples **curl** ```sh #!/bin/sh # Analyse a conversation again. It costs credit, like any analysis. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/analysis" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Analyse a conversation again. It costs credit, like any analysis. const response = await fetch("https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/analysis", { method: "POST", 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 # Analyse a conversation again. It costs credit, like any analysis. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/analysis", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Analyse a conversation again. It costs credit, like any analysis. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/analysis", 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 // Analyse a conversation again. It costs credit, like any analysis. 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/analysis")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("POST", 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 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 // Analyse a conversation again. It costs credit, like any analysis. 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.Post, "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/analysis") { }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => "", ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Get a link to a conversation's recording > GET /v1/conversations/{conversation_id}/recording A link to the audio that works for 5 minutes: a stereo Ogg file with the caller on the left and the agent on the right. Each key may ask for 60 a minute and 2,000 a day, and every link is recorded in the audit log. Needs `recordings:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `conversation_id` | path | string (uuid) | Yes | | ## Answer `200` with [Recording](/reference/objects/Recording). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such conversation, or it has no recording. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Get a link to a recording. The link works for five minutes, so download the audio straight away. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Get a link to a recording. The link works for five minutes, so download the audio straight away. const response = await fetch("https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording", { 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 # Get a link to a recording. The link works for five minutes, so download the audio straight away. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Get a link to a recording. The link works for five minutes, so download the audio straight away. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording", 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 // Get a link to a recording. The link works for five minutes, so download the audio straight away. 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording")) .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 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 // Get a link to a recording. The link works for five minutes, so download the audio straight away. 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/recording") { }; 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 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"; ``` --- # Get a conversation's transcript > GET /v1/conversations/{conversation_id}/transcript Everything that was said, in order, in one response. Needs `transcripts:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `conversation_id` | path | string (uuid) | Yes | | ## Answer `200` with [Transcript](/reference/objects/Transcript). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such conversation. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Read a transcript curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/transcript" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read a transcript const response = await fetch("https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/transcript", { 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 # Read a transcript # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/transcript", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read a transcript package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/transcript", 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 // Read a transcript 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/transcript")) .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 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 // Read a transcript 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/conversations/5f0c9a52-7d3e-4b1a-9c8f-6e2d4a0b3c1d/transcript") { }; 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 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"; ``` --- # Get a command > GET /v1/conversations/{conversation_id}/commands/{command_id} How something a call was asked to do went: `sent`, `taken` once the call's agent has it, then `done` or `failed`. Needs `calls:control`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `conversation_id` | path | string (uuid) | Yes | | | `command_id` | path | string (uuid) | Yes | | ## Answer `200` with [ConversationCommandObject](/reference/objects/ConversationCommandObject). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such conversation or command. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Read how a command went curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/commands/6c8e0a2c-4e6a-4c8e-b0a2-c4e6a8cafc0e" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read how a command went const response = await fetch("https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/commands/6c8e0a2c-4e6a-4c8e-b0a2-c4e6a8cafc0e", { 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 # Read how a command went # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/commands/6c8e0a2c-4e6a-4c8e-b0a2-c4e6a8cafc0e", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read how a command went package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/commands/6c8e0a2c-4e6a-4c8e-b0a2-c4e6a8cafc0e", 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 // Read how a command went 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/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/commands/6c8e0a2c-4e6a-4c8e-b0a2-c4e6a8cafc0e")) .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 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 // Read how a command went 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/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/commands/6c8e0a2c-4e6a-4c8e-b0a2-c4e6a8cafc0e") { }; 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 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"; ``` --- # Follow a call's transcript live > GET /v1/conversations/{conversation_id}/live The lines said on a call since `after`, as they are said. Answers as soon as there is a line after `after`, or after `wait` seconds with none; send `next_after` back as `after` and ask again, until `ended` is true. Lines are kept for a day: after that, read the conversation's transcript. Needs `transcripts:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `conversation_id` | path | string (uuid) | Yes | | | `after` | query | integer | No | The last `seq` you have read. | | `wait` | query | integer | No | How long to wait for a line, in seconds. | ## Answer `200` with [LiveTranscript](/reference/objects/LiveTranscript). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such conversation. | | `409` | A chat or a WhatsApp conversation has no live transcript. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Follow a call's transcript live. Send next_after back as after, and ask again until ended is true. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/live?after=0&wait=20" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Follow a call's transcript live. Send next_after back as after, and ask again until ended is true. const response = await fetch("https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/live?after=0&wait=20", { 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 # Follow a call's transcript live. Send next_after back as after, and ask again until ended is true. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/live", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "after": 0, "wait": 20, }, timeout=60, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Follow a call's transcript live. Send next_after back as after, and ask again until ended is true. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/live?after=0&wait=20", 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 // Follow a call's transcript live. Send next_after back as after, and ask again until ended is true. 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/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/live?after=0&wait=20")) .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 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 // Follow a call's transcript live. Send next_after back as after, and ask again until ended is true. 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/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/live?after=0&wait=20") { }; 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 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"; ``` --- # Give the agent a note > POST /v1/conversations/{conversation_id}/notes Information from your own systems for the agent to use — a payment that went through, an order that shipped. The caller does not hear it, and it reaches the agent as information, never as instructions: it cannot change what the agent is for. With `respond`, the agent answers at once. Needs `calls:control`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `conversation_id` | path | string (uuid) | Yes | | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `respond` | boolean | No | Whether the agent answers it at once, rather than using it on its next turn. | | `text` | string | Yes | Information for the agent from your own systems. It reaches the agent as information, never as instructions, and the caller does not hear it. | ## Answer `202` with [ConversationCommandObject](/reference/objects/ConversationCommandObject). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such conversation. | | `409` | The call has not been answered, has ended, or is not a call. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Give the agent a note. The caller does not hear it. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/notes" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "text": "The deposit for booking 4471 has been paid.", "respond": false }' ``` **JavaScript** ```js // Give the agent a note. The caller does not hear it. const response = await fetch("https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/notes", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "text": "The deposit for booking 4471 has been paid.", "respond": false }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Give the agent a note. The caller does not hear it. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/notes", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "text": "The deposit for booking 4471 has been paid.", "respond": False, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Give the agent a note. The caller does not hear it. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "text": "The deposit for booking 4471 has been paid.", "respond": false }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/notes", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Give the agent a note. The caller does not hear it. 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 { String body = """ { "text": "The deposit for booking 4471 has been paid.", "respond": false } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/notes")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Give the agent a note. The caller does not hear it. 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.Post, "https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/notes") { Content = new StringContent( """ { "text": "The deposit for booking 4471 has been paid.", "respond": false } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "text" => "The deposit for booking 4471 has been paid.", "respond" => false, ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Have the agent say something > POST /v1/conversations/{conversation_id}/say The agent says `text` on the call, word for word and in its own voice, once it has finished what it is saying. Answers at once with the command. Needs `calls:control`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `conversation_id` | path | string (uuid) | Yes | | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `text` | string | Yes | Said by the agent, word for word, in its voice. | ## Answer `202` with [ConversationCommandObject](/reference/objects/ConversationCommandObject). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such conversation. | | `409` | The call has not been answered, has ended, or is not a call. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Have the agent say something curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/say" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "text": "Your table for four is booked for seven this evening." }' ``` **JavaScript** ```js // Have the agent say something const response = await fetch("https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/say", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "text": "Your table for four is booked for seven this evening." }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Have the agent say something # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/say", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "text": "Your table for four is booked for seven this evening.", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Have the agent say something package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "text": "Your table for four is booked for seven this evening." }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/say", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Have the agent say something 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 { String body = """ { "text": "Your table for four is booked for seven this evening." } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/say")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Have the agent say something 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.Post, "https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/say") { Content = new StringContent( """ { "text": "Your table for four is booked for seven this evening." } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "text" => "Your table for four is booked for seven this evening.", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Transfer a call > POST /v1/conversations/{conversation_id}/transfer Put the caller through to a person: the agent says its own transfer line, the number rings, and the agent leaves the call once somebody answers — or tells the caller nobody could. `to_number`, or the agent's own transfer number when you leave it out, is checked like any number an agent calls. Once per call, and phone calls only. Needs `calls:control`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `conversation_id` | path | string (uuid) | Yes | | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `summary` | string | No | What the person who answers is told. | | `to_number` | string or null | No | Where to put the caller through, in international format, like `+966501234567`. Leave it out for the agent's own transfer number. | ## Answer `202` with [ConversationCommandObject](/reference/objects/ConversationCommandObject). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such conversation. | | `409` | Not a phone call, not answered, ended, or already transferred. | | `422` | The number may not be called, or the agent has none of its own. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Transfer a call. Phone calls only, once per call. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/transfer" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "to_number": "+966501234567", "summary": "Wants a private room for twenty." }' ``` **JavaScript** ```js // Transfer a call. Phone calls only, once per call. const response = await fetch("https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/transfer", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "to_number": "+966501234567", "summary": "Wants a private room for twenty." }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Transfer a call. Phone calls only, once per call. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/transfer", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "to_number": "+966501234567", "summary": "Wants a private room for twenty.", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Transfer a call. Phone calls only, once per call. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "to_number": "+966501234567", "summary": "Wants a private room for twenty." }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/transfer", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Transfer a call. Phone calls only, once per call. 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 { String body = """ { "to_number": "+966501234567", "summary": "Wants a private room for twenty." } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/transfer")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Transfer a call. Phone calls only, once per call. 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.Post, "https://api.aigently.ai/v1/conversations/5b7d9f1b-3d5f-4b7d-a9f1-b3d5f7b9dbfd/transfer") { Content = new StringContent( """ { "to_number": "+966501234567", "summary": "Wants a private room for twenty." } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "to_number" => "+966501234567", "summary" => "Wants a private room for twenty.", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # List events > GET /v1/events Every event sent to webhook receivers in the last 30 days, oldest first, whether or not any receiver heard it — each with the id its deliveries carry. Keep the last page's `next_cursor` and ask again later for what happened since. Events from the last minute wait for the next page. `conversation.transcript` events also need `transcripts:read`. Needs `conversations:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `type` | query | array of string or null | No | An event type, like `conversation.ended`. Repeatable. | | `conversation_id` | query | string (uuid) or null | No | Only the events about this conversation. | | `created_after` | query | string (date-time) or null | No | Only events from this time on. | | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [EventList](/reference/objects/EventList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Read the event feed. Keep the last page's next_cursor and send it back as cursor= next time. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/events?type=conversation.ended&limit=50" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read the event feed. Keep the last page's next_cursor and send it back as cursor= next time. const response = await fetch("https://api.aigently.ai/v1/events?type=conversation.ended&limit=50", { 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 # Read the event feed. Keep the last page's next_cursor and send it back as cursor= next time. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/events", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "type": "conversation.ended", "limit": 50, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read the event feed. Keep the last page's next_cursor and send it back as cursor= next time. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/events?type=conversation.ended&limit=50", 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 // Read the event feed. Keep the last page's next_cursor and send it back as cursor= next time. 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/events?type=conversation.ended&limit=50")) .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 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 // Read the event feed. Keep the last page's next_cursor and send it back as cursor= next time. 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/events?type=conversation.ended&limit=50") { }; 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 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"; ``` --- # List webhook receivers > GET /v1/webhooks The receivers in the projects this key reaches, on its own side of test mode: a test key lists test receivers. Needs `webhooks:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `project_id` | query | string (uuid) or null | No | Only this project's. | ## Answer `200` with [WebhookReceiverList](/reference/objects/WebhookReceiverList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # List webhook receivers curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/webhooks" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List webhook receivers const response = await fetch("https://api.aigently.ai/v1/webhooks", { 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 # List webhook receivers # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/webhooks", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List webhook receivers package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/webhooks", 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 // List webhook receivers 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/webhooks")) .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 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 // List webhook receivers 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/webhooks") { }; 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 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"; ``` --- # Create a webhook receiver > POST /v1/webhooks A new receiver in one of this key's projects — live for a live key, test for a test key. The address must be public `https`. At most 10 per project. The signing secret is in this answer and never again. Needs `webhooks:write`. ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `agent_ids` | array of string (uuid) | No | Only these agents' conversations. Empty is every agent in the project. | | `events` | array of string or null | No | The events it hears. Leave it out for the defaults: everything but `conversation.transcript` and `form.abandoned`. | | `include_values` | boolean | No | Whether events carry the values a conversation started with, your metadata and both phone numbers. | | `project_id` | string (uuid) | Yes | The project whose conversations it hears. | | `url` | string | Yes | Where events are POSTed: a public `https` address. | ## Answer `201` with [WebhookReceiverWithSecret](/reference/objects/WebhookReceiverWithSecret). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such project. | | `409` | The project is frozen. | | `422` | The address, an event or an agent does not fit, or the project is full. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Create a webhook receiver. Keep the secret in the answer: it is shown once. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/webhooks" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "url": "https://hooks.aigently.ai/aigently", "events": [ "conversation.ended", "conversation.analyzed" ] }' ``` **JavaScript** ```js // Create a webhook receiver. Keep the secret in the answer: it is shown once. const response = await fetch("https://api.aigently.ai/v1/webhooks", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "url": "https://hooks.aigently.ai/aigently", "events": [ "conversation.ended", "conversation.analyzed" ] }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Create a webhook receiver. Keep the secret in the answer: it is shown once. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/webhooks", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "url": "https://hooks.aigently.ai/aigently", "events": ["conversation.ended", "conversation.analyzed"], }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Create a webhook receiver. Keep the secret in the answer: it is shown once. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "url": "https://hooks.aigently.ai/aigently", "events": [ "conversation.ended", "conversation.analyzed" ] }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/webhooks", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Create a webhook receiver. Keep the secret in the answer: it is shown once. 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 { String body = """ { "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "url": "https://hooks.aigently.ai/aigently", "events": [ "conversation.ended", "conversation.analyzed" ] } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/webhooks")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Create a webhook receiver. Keep the secret in the answer: it is shown once. 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.Post, "https://api.aigently.ai/v1/webhooks") { Content = new StringContent( """ { "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "url": "https://hooks.aigently.ai/aigently", "events": [ "conversation.ended", "conversation.analyzed" ] } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "project_id" => "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e", "url" => "https://hooks.aigently.ai/aigently", "events" => ["conversation.ended", "conversation.analyzed"], ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Get a webhook receiver > GET /v1/webhooks/{receiver_id} One receiver, without its secret. Needs `webhooks:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `receiver_id` | path | string (uuid) | Yes | | ## Answer `200` with [WebhookReceiver](/reference/objects/WebhookReceiver). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such receiver. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Read a webhook receiver curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read a webhook receiver const response = await fetch("https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c", { 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 # Read a webhook receiver # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read a webhook receiver package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c", 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 // Read a webhook receiver 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/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c")) .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 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 // Read a webhook receiver 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/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c") { }; 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 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"; ``` --- # Change a webhook receiver > PATCH /v1/webhooks/{receiver_id} Change the events it hears, switch it off or on, or limit it to some agents. Its address cannot change: make a new receiver for a new address. Needs `webhooks:write`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `receiver_id` | path | string (uuid) | Yes | | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `agent_ids` | array of string (uuid) or null | No | Only these agents' conversations; an empty list is every agent. | | `enabled` | boolean or null | No | False stops its deliveries. | | `events` | array of string or null | No | The events it hears. | | `include_values` | boolean or null | No | Whether events carry a conversation's values and numbers. | ## Answer `200` with [WebhookReceiver](/reference/objects/WebhookReceiver). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such receiver. | | `409` | The project is frozen. | | `422` | An event or an agent does not fit. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Change what a receiver hears curl -sS --fail-with-body -X PATCH "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "events": [ "conversation.ended" ], "include_values": false }' ``` **JavaScript** ```js // Change what a receiver hears const response = await fetch("https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "events": [ "conversation.ended" ], "include_values": false }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Change what a receiver hears # pip install httpx import os import httpx response = httpx.patch( "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "events": ["conversation.ended"], "include_values": False, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Change what a receiver hears package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "events": [ "conversation.ended" ], "include_values": false }`) request, err := http.NewRequest("PATCH", "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Change what a receiver hears 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 { String body = """ { "events": [ "conversation.ended" ], "include_values": false } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("PATCH", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Change what a receiver hears 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.Patch, "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c") { Content = new StringContent( """ { "events": [ "conversation.ended" ], "include_values": false } """, Encoding.UTF8, "application/json"), }; 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 "PATCH", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "events" => ["conversation.ended"], "include_values" => false, ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Delete a webhook receiver > DELETE /v1/webhooks/{receiver_id} Stop and remove a receiver, with its deliveries. Events it would have heard stay in the event feed. Needs `webhooks:write`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `receiver_id` | path | string (uuid) | Yes | | ## Answer `200` with [Deleted](/reference/objects/Deleted). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such receiver. | | `409` | The project is frozen. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Delete a webhook receiver curl -sS --fail-with-body -X DELETE "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Delete a webhook receiver const response = await fetch("https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c", { method: "DELETE", 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 # Delete a webhook receiver # pip install httpx import os import httpx response = httpx.delete( "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Delete a webhook receiver package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("DELETE", "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c", 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 // Delete a webhook receiver 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/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("DELETE", 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 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 // Delete a webhook receiver 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.Delete, "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c") { }; 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 "DELETE", 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"; ``` --- # List a receiver's deliveries > GET /v1/webhooks/{receiver_id}/deliveries What was sent to this receiver in the last 30 days, newest first, and how each attempt went. Needs `webhooks:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `receiver_id` | path | string (uuid) | Yes | | | `status` | query | [WebhookDeliveryStatus](/reference/objects/WebhookDeliveryStatus) or null | No | `pending`, `delivered` or `failed`. | | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [WebhookDeliveryList](/reference/objects/WebhookDeliveryList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such receiver. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # List what a receiver was sent curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries?status=failed" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List what a receiver was sent const response = await fetch("https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries?status=failed", { 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 # List what a receiver was sent # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "status": "failed", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List what a receiver was sent package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries?status=failed", 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 // List what a receiver was sent 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/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries?status=failed")) .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 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 // List what a receiver was sent 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/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries?status=failed") { }; 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 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"; ``` --- # Send a delivery again > POST /v1/webhooks/{receiver_id}/deliveries/{delivery_id}/resend Put a failed delivery back in the queue with a fresh set of retries — after your receiver was down, say. One already waiting is left as it is; one delivered is refused. Needs `webhooks:write`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `receiver_id` | path | string (uuid) | Yes | | | `delivery_id` | path | string (uuid) | Yes | | ## Answer `200` with [WebhookDelivery](/reference/objects/WebhookDelivery). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such receiver or delivery. | | `409` | The receiver is switched off, the delivery was delivered, or the project is frozen. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Send a failed delivery again curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries/9e1b3d5f-7a9c-4e2b-8d4f-6a8c0e2b4d6f/resend" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Send a failed delivery again const response = await fetch("https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries/9e1b3d5f-7a9c-4e2b-8d4f-6a8c0e2b4d6f/resend", { method: "POST", 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 # Send a failed delivery again # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries/9e1b3d5f-7a9c-4e2b-8d4f-6a8c0e2b4d6f/resend", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Send a failed delivery again package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries/9e1b3d5f-7a9c-4e2b-8d4f-6a8c0e2b4d6f/resend", 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 // Send a failed delivery again 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/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries/9e1b3d5f-7a9c-4e2b-8d4f-6a8c0e2b4d6f/resend")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("POST", 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 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 // Send a failed delivery again 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.Post, "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/deliveries/9e1b3d5f-7a9c-4e2b-8d4f-6a8c0e2b4d6f/resend") { }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => "", ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Change a webhook receiver's secret > POST /v1/webhooks/{receiver_id}/rotate-secret A new signing secret, in this answer and never again. With `keep_previous_for`, the old one keeps signing beside it until then — every delivery carries a signature from each — so your receiver can be updated first. `now`, the default, is the answer to a leak. Needs `webhooks:write`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `receiver_id` | path | string (uuid) | Yes | | ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `keep_previous_for` | one of `now`, `1h`, `24h`, `7d` | No | How long the old secret keeps signing beside the new one: `now` ends it at once, which is the answer to a leak; an overlap lets you update your receiver first. | ## Answer `200` with [WebhookReceiverWithSecret](/reference/objects/WebhookReceiverWithSecret). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such receiver. | | `409` | The project is frozen. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Change a receiver's secret, keeping the old one for a day curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/rotate-secret" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "keep_previous_for": "24h" }' ``` **JavaScript** ```js // Change a receiver's secret, keeping the old one for a day const response = await fetch("https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/rotate-secret", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "keep_previous_for": "24h" }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Change a receiver's secret, keeping the old one for a day # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/rotate-secret", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "keep_previous_for": "24h", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Change a receiver's secret, keeping the old one for a day package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "keep_previous_for": "24h" }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/rotate-secret", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Change a receiver's secret, keeping the old one for a day 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 { String body = """ { "keep_previous_for": "24h" } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/rotate-secret")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Change a receiver's secret, keeping the old one for a day 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.Post, "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/rotate-secret") { Content = new StringContent( """ { "keep_previous_for": "24h" } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "keep_previous_for" => "24h", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Send a test event > POST /v1/webhooks/{receiver_id}/test One signed `webhook.test` event to this receiver, at once, through the same path every delivery takes — and whether it arrived. Needs `webhooks:write`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `receiver_id` | path | string (uuid) | Yes | | ## Answer `200` with [WebhookTest](/reference/objects/WebhookTest). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `404` | This key reaches no such receiver. | | `409` | The project is frozen. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Send a test event curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/test" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Send a test event const response = await fetch("https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/test", { method: "POST", 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 # Send a test event # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/test", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Send a test event package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/test", 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 // Send a test event 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/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/test")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .method("POST", 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 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 // Send a test event 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.Post, "https://api.aigently.ai/v1/webhooks/6d8f0a2c-4e6b-4d8f-9a1c-3e5b7d9f1a3c/test") { }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), ], CURLOPT_POSTFIELDS => "", ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Get the credit balance > GET /v1/billing/balance The organization's credit: what is on the account, what can still be spent, and what this month has spent. Needs `billing:read`. ## Answer `200` with [CreditBalance](/reference/objects/CreditBalance). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Read the credit balance curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/billing/balance" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read the credit balance const response = await fetch("https://api.aigently.ai/v1/billing/balance", { 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 # Read the credit balance # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/billing/balance", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read the credit balance package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/billing/balance", 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 // Read the credit balance 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/billing/balance")) .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 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 // Read the credit balance 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/billing/balance") { }; 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 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"; ``` --- # List credit transactions > GET /v1/billing/transactions Every movement of credit, newest first: each conversation's charge, top-ups, refunds. A key limited to some projects reads their charges alone; a test key, what test keys spent. Needs `billing:read`. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `conversation_id` | query | string (uuid) or null | No | Only this conversation's charges. | | `kind` | query | array of [CreditEntryKind](/reference/objects/CreditEntryKind) or null | No | Only these kinds. Repeatable. | | `created_after` | query | string (date-time) or null | No | From this time on. | | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [CreditTransactionList](/reference/objects/CreditTransactionList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # List what was charged curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/billing/transactions?limit=20" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // List what was charged const response = await fetch("https://api.aigently.ai/v1/billing/transactions?limit=20", { 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 # List what was charged # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/billing/transactions", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "limit": 20, }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // List what was charged package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/billing/transactions?limit=20", 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 // List what was charged 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/billing/transactions?limit=20")) .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 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 // List what was charged 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/billing/transactions?limit=20") { }; 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 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"; ``` --- # List audit events > GET /v1/audit-events Everything people and API keys did in the organization, oldest first: the console's audit log. Keep the last page's `next_cursor` and ask again later for what was done since. Events from the last minute wait for the next page. Kept 365 days. Needs `audit:read` and a key that reaches every project; a test key reads none. ## Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `action` | query | array of string or null | No | An action, like `agent.published`. Repeatable. | | `created_after` | query | string (date-time) or null | No | Only events from this time on. | | `limit` | query | integer | No | How many to return, 1 to 100. | | `cursor` | query | string or null | No | `next_cursor` from the previous page, with the same filters. | ## Answer `200` with [AuditEventList](/reference/objects/AuditEventList). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | The key lacks a permission, a live key was sent from a browser, or the organization is frozen and the request would change something. | | `422` | Validation Error | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Read the audit log. With a live key that reaches every project. Keep the last page's `next_cursor`. curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/audit-events?action=agent.published" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" ``` **JavaScript** ```js // Read the audit log. With a live key that reaches every project. Keep the last page's `next_cursor`. const response = await fetch("https://api.aigently.ai/v1/audit-events?action=agent.published", { 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 # Read the audit log. With a live key that reaches every project. Keep the last page's `next_cursor`. # pip install httpx import os import httpx response = httpx.get( "https://api.aigently.ai/v1/audit-events", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, params={ "action": "agent.published", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Read the audit log. With a live key that reaches every project. Keep the last page's `next_cursor`. package main import ( "fmt" "io" "net/http" "os" ) func main() { request, err := http.NewRequest("GET", "https://api.aigently.ai/v1/audit-events?action=agent.published", 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 // Read the audit log. With a live key that reaches every project. Keep the last page's `next_cursor`. 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/audit-events?action=agent.published")) .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 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 // Read the audit log. With a live key that reaches every project. Keep the last page's `next_cursor`. 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/audit-events?action=agent.published") { }; 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 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"; ``` --- # Make a test call to an agent > POST /v1/test/inbound-calls With a **test key** only: somebody calls one of your inbound agents from a test number. The agent's test lookup address is asked — or its sample answer used, with no request — and the answer says what the lookup made of it and the greeting it produced. The conversation then plays out like any test call: events to your test receivers, nothing real rung, nothing charged. ## Body Sent as JSON. A field this operation does not take is refused, so a typo fails loudly. | Field | Type | Required | Description | |---|---|---|---| | `agent_id` | string (uuid) or null | No | The inbound agent the call reaches. Or send `phone_number_id`. | | `from_number` | string | Yes | The test number the call comes from, like `+12025550100`. | | `phone_number_id` | string (uuid) or null | No | One of your numbers; the call reaches the agent it rings. | ## Answer `201` with [TestInboundCall](/reference/objects/TestInboundCall). ## Errors Every error is a [problem document](/errors) with a stable `code`. | Status | When | |---|---| | `401` | The key is missing, mistyped, unknown, revoked or expired. | | `403` | Only a test key makes test calls. | | `404` | This key reaches no such agent or number. | | `409` | The agent answers no calls, or its project is frozen. | | `422` | `from_number` is not a test number, or the request does not fit. | | `429` | Too many requests for this key or its organization; see `Retry-After`. | | `500` | Something went wrong on our side. Quote the `request_id` to support. | ## Examples **curl** ```sh #!/bin/sh # Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/test/inbound-calls" \ -H "Authorization: Bearer $AIGENTLY_API_KEY" \ --json '{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" }' ``` **JavaScript** ```js // Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. const response = await fetch("https://api.aigently.ai/v1/test/inbound-calls", { method: "POST", headers: { Authorization: `Bearer ${process.env.AIGENTLY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" }), }); const answer = await response.json(); if (!response.ok) throw new Error(`${answer.code}: ${answer.detail}`); console.log(answer); ``` **Python** ```python # Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. # pip install httpx import os import httpx response = httpx.post( "https://api.aigently.ai/v1/test/inbound-calls", headers={ "Authorization": f"Bearer {os.environ['AIGENTLY_API_KEY']}", }, json={ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100", }, ) if response.is_error: raise SystemExit(response.text) print(response.json()) ``` **Go** ```go // Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. package main import ( "bytes" "fmt" "io" "net/http" "os" ) func main() { payload := []byte(`{ "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" }`) request, err := http.NewRequest("POST", "https://api.aigently.ai/v1/test/inbound-calls", bytes.NewReader(payload)) if err != nil { panic(err) } request.Header.Set("Authorization", "Bearer "+os.Getenv("AIGENTLY_API_KEY")) request.Header.Set("Content-Type", "application/json") 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 // Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. 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 { String body = """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" } """; HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.aigently.ai/v1/test/inbound-calls")) .header("Authorization", "Bearer " + System.getenv("AIGENTLY_API_KEY")) .header("Content-Type", "application/json") .method("POST", HttpRequest.BodyPublishers.ofString(body)) .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 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 // Make a test call to an agent. Test keys only. It asks the agent's test lookup and plays a scripted call. 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.Post, "https://api.aigently.ai/v1/test/inbound-calls") { Content = new StringContent( """ { "agent_id": "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number": "+12025550100" } """, Encoding.UTF8, "application/json"), }; 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 true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("AIGENTLY_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "agent_id" => "3c7d9e1f-5a2b-4c6d-8e0f-1a3b5c7d9e2f", "from_number" => "+12025550100", ]), ]); $body = curl_exec($curl); if (curl_getinfo($curl, CURLINFO_RESPONSE_CODE) >= 400) { fwrite(STDERR, $body . "\n"); exit(1); } echo $body, "\n"; ``` --- # Objects > What the API answers with. What the API answers with. Every object says what it is in its `object` field, and may gain fields at any time — read the ones you know and ignore the rest. | Object | What it is | |---|---| | [Agent](/reference/objects/Agent) | The Agent object. | | [AgentDefinition](/reference/objects/AgentDefinition) | An agent as a document: everything about how it behaves, and everything outside it by name | | [AgentDeleted](/reference/objects/AgentDeleted) | The AgentDeleted object. | | [AgentDetail](/reference/objects/AgentDetail) | The AgentDetail object. | | [AgentDirection](/reference/objects/AgentDirection) | The AgentDirection object. | | [AgentKind](/reference/objects/AgentKind) | The AgentKind object. | | [AgentList](/reference/objects/AgentList) | The AgentList object. | | [AgentPublishRequest](/reference/objects/AgentPublishRequest) | The AgentPublishRequest object. | | [AgentStatus](/reference/objects/AgentStatus) | The AgentStatus object. | | [AgentVersionList](/reference/objects/AgentVersionList) | The AgentVersionList object. | | [AgentVersionObject](/reference/objects/AgentVersionObject) | One published version of an agent: what pinning a conversation to it gets. | | [AgentWritten](/reference/objects/AgentWritten) | The AgentWritten object. | | [Analysis](/reference/objects/Analysis) | The Analysis object. | | [Attachment](/reference/objects/Attachment) | The Attachment object. | | [AuditActor](/reference/objects/AuditActor) | The AuditActor object. | | [AuditEvent](/reference/objects/AuditEvent) | One thing somebody did in the organization: in the console, or with an API key. | | [AuditEventList](/reference/objects/AuditEventList) | The AuditEventList object. | | [CallWindow](/reference/objects/CallWindow) | The hours a call may start in, read in one time zone (`services/calling_hours`). | | [Campaign](/reference/objects/Campaign) | The Campaign object. | | [CampaignCallbacks](/reference/objects/CampaignCallbacks) | The CampaignCallbacks object. | | [CampaignCallbacksObject](/reference/objects/CampaignCallbacksObject) | The CampaignCallbacksObject object. | | [CampaignCallingHours](/reference/objects/CampaignCallingHours) | The CampaignCallingHours object. | | [CampaignCallingHoursObject](/reference/objects/CampaignCallingHoursObject) | The CampaignCallingHoursObject object. | | [CampaignContact](/reference/objects/CampaignContact) | The CampaignContact object. | | [CampaignContactCreate](/reference/objects/CampaignContactCreate) | The CampaignContactCreate object. | | [CampaignContactList](/reference/objects/CampaignContactList) | The CampaignContactList object. | | [CampaignContactStatus](/reference/objects/CampaignContactStatus) | The CampaignContactStatus object. | | [CampaignContactsAdded](/reference/objects/CampaignContactsAdded) | The CampaignContactsAdded object. | | [CampaignCounts](/reference/objects/CampaignCounts) | The CampaignCounts object. | | [CampaignList](/reference/objects/CampaignList) | The CampaignList object. | | [CampaignPacing](/reference/objects/CampaignPacing) | The CampaignPacing object. | | [CampaignPacingObject](/reference/objects/CampaignPacingObject) | The CampaignPacingObject object. | | [CampaignResume](/reference/objects/CampaignResume) | The CampaignResume object. | | [CampaignStatus](/reference/objects/CampaignStatus) | The CampaignStatus object. | | [CampaignVoicemail](/reference/objects/CampaignVoicemail) | The CampaignVoicemail object. | | [CampaignVoicemailObject](/reference/objects/CampaignVoicemailObject) | The CampaignVoicemailObject object. | | [Capabilities](/reference/objects/Capabilities) | What this deployment of Aigently runs — a company's own copy may switch parts off. | | [Channel](/reference/objects/Channel) | The Channel object. | | [ChatTurn](/reference/objects/ChatTurn) | One exchange: what the agent said back, and where the conversation stands after it. | | [Contact](/reference/objects/Contact) | The Contact object. | | [ContactDeleted](/reference/objects/ContactDeleted) | The ContactDeleted object. | | [ContactFields](/reference/objects/ContactFields) | The ContactFields object. | | [ContactImported](/reference/objects/ContactImported) | The ContactImported object. | | [ContactList](/reference/objects/ContactList) | The ContactList object. | | [Context](/reference/objects/Context) | What the context lookup made of an inbound call (§9.2). | | [ContextProblem](/reference/objects/ContextProblem) | The ContextProblem object. | | [Conversation](/reference/objects/Conversation) | `docs/plans/public-api-and-sdks.md` §6.4 — built by `services/conversation_object`. | | [ConversationCommandObject](/reference/objects/ConversationCommandObject) | Something a live call was asked to do. | | [ConversationList](/reference/objects/ConversationList) | The ConversationList object. | | [ConversationListItem](/reference/objects/ConversationListItem) | A conversation as the list returns it | | [ConversationMode](/reference/objects/ConversationMode) | The ConversationMode object. | | [ConversationStatus](/reference/objects/ConversationStatus) | The ConversationStatus object. | | [ConversationWithTranscript](/reference/objects/ConversationWithTranscript) | The ConversationWithTranscript object. | | [Cost](/reference/objects/Cost) | The Cost object. | | [CreditBalance](/reference/objects/CreditBalance) | The CreditBalance object. | | [CreditEntryKind](/reference/objects/CreditEntryKind) | The CreditEntryKind object. | | [CreditTransaction](/reference/objects/CreditTransaction) | The CreditTransaction object. | | [CreditTransactionList](/reference/objects/CreditTransactionList) | The CreditTransactionList object. | | [Criterion](/reference/objects/Criterion) | The Criterion object. | | [Deleted](/reference/objects/Deleted) | The Deleted object. | | [DeletedConversation](/reference/objects/DeletedConversation) | The DeletedConversation object. | | [DeletedConversationList](/reference/objects/DeletedConversationList) | The DeletedConversationList object. | | [Direction](/reference/objects/Direction) | The Direction object. | | [Disposition](/reference/objects/Disposition) | The Disposition object. | | [DoNotCallEntry](/reference/objects/DoNotCallEntry) | The DoNotCallEntry object. | | [DoNotCallList](/reference/objects/DoNotCallList) | The DoNotCallList object. | | [DoNotCallRemoved](/reference/objects/DoNotCallRemoved) | The DoNotCallRemoved object. | | [EndedBy](/reference/objects/EndedBy) | The EndedBy object. | | [EvaluationExpectation](/reference/objects/EvaluationExpectation) | The EvaluationExpectation object. | | [EvaluationExpectationCreate](/reference/objects/EvaluationExpectationCreate) | The EvaluationExpectationCreate object. | | [EvaluationLatest](/reference/objects/EvaluationLatest) | The EvaluationLatest object. | | [EvaluationList](/reference/objects/EvaluationList) | The EvaluationList object. | | [EvaluationObject](/reference/objects/EvaluationObject) | A saved conversation: what a caller says, and what must be true of the agent's replies. | | [EvaluationResult](/reference/objects/EvaluationResult) | The EvaluationResult object. | | [EvaluationRunObject](/reference/objects/EvaluationRunObject) | One rehearsal of every saved conversation an agent has. | | [EvaluationTurn](/reference/objects/EvaluationTurn) | The EvaluationTurn object. | | [EvaluationVerdict](/reference/objects/EvaluationVerdict) | The EvaluationVerdict object. | | [Event](/reference/objects/Event) | One event, as a webhook receiver was sent it — under the same id. | | [EventList](/reference/objects/EventList) | The EventList object. | | [Handoff](/reference/objects/Handoff) | The Handoff object. | | [Include](/reference/objects/Include) | The Include object. | | [KnowledgeBaseList](/reference/objects/KnowledgeBaseList) | The KnowledgeBaseList object. | | [KnowledgeBaseObject](/reference/objects/KnowledgeBaseObject) | The KnowledgeBaseObject object. | | [KnowledgeCrawl](/reference/objects/KnowledgeCrawl) | The KnowledgeCrawl object. | | [KnowledgeCrawlList](/reference/objects/KnowledgeCrawlList) | The KnowledgeCrawlList object. | | [KnowledgeDocument](/reference/objects/KnowledgeDocument) | The KnowledgeDocument object. | | [KnowledgeDocumentDeleted](/reference/objects/KnowledgeDocumentDeleted) | The KnowledgeDocumentDeleted object. | | [KnowledgeDocumentList](/reference/objects/KnowledgeDocumentList) | The KnowledgeDocumentList object. | | [KnowledgeDocumentStatus](/reference/objects/KnowledgeDocumentStatus) | The KnowledgeDocumentStatus object. | | [Language](/reference/objects/Language) | The Language object. | | [Languages](/reference/objects/Languages) | The Languages object. | | [Limits](/reference/objects/Limits) | Every ceiling that applies to this key, and how much of the calls one is in use now. | | [LiveLineObject](/reference/objects/LiveLineObject) | One line of a call, as it was said. | | [LiveTranscript](/reference/objects/LiveTranscript) | What was said on a call since `after`, as it is said. | | [McpServerList](/reference/objects/McpServerList) | The McpServerList object. | | [McpServerObject](/reference/objects/McpServerObject) | One remote MCP server whose tools an agent can be given. | | [Me](/reference/objects/Me) | The Me object. | | [Order](/reference/objects/Order) | The Order object. | | [OrganizationRef](/reference/objects/OrganizationRef) | The OrganizationRef object. | | [Outcome](/reference/objects/Outcome) | The Outcome object. | | [PhoneNumber](/reference/objects/PhoneNumber) | The PhoneNumber object. | | [PhoneNumberList](/reference/objects/PhoneNumberList) | The PhoneNumberList object. | | [Problem](/reference/objects/Problem) | RFC 9457 problem details — what every `/v1` error answers with. | | [Project](/reference/objects/Project) | The Project object. | | [ProjectList](/reference/objects/ProjectList) | The ProjectList object. | | [Reach](/reference/objects/Reach) | The Reach object. | | [Recording](/reference/objects/Recording) | The Recording object. | | [Removed](/reference/objects/Removed) | The Removed object. | | [ScheduledCall](/reference/objects/ScheduledCall) | The ScheduledCall object. | | [ScheduledCallList](/reference/objects/ScheduledCallList) | The ScheduledCallList object. | | [ScheduledCallStatus](/reference/objects/ScheduledCallStatus) | The ScheduledCallStatus object. | | [TestInboundCall](/reference/objects/TestInboundCall) | The TestInboundCall object. | | [TestLookup](/reference/objects/TestLookup) | What the agent's context lookup made of a test call. | | [ToolList](/reference/objects/ToolList) | The ToolList object. | | [ToolObject](/reference/objects/ToolObject) | One tool: an HTTP request an agent can make mid-conversation, described for its model. | | [Transcript](/reference/objects/Transcript) | The Transcript object. | | [TranscriptEntry](/reference/objects/TranscriptEntry) | The TranscriptEntry object. | | [UnboundReference](/reference/objects/UnboundReference) | The UnboundReference object. | | [VaultSecretList](/reference/objects/VaultSecretList) | The VaultSecretList object. | | [VaultSecretObject](/reference/objects/VaultSecretObject) | A tool credential in the vault | | [WebCall](/reference/objects/WebCall) | The WebCall object. | | [WebhookDelivery](/reference/objects/WebhookDelivery) | The WebhookDelivery object. | | [WebhookDeliveryList](/reference/objects/WebhookDeliveryList) | The WebhookDeliveryList object. | | [WebhookDeliveryStatus](/reference/objects/WebhookDeliveryStatus) | The WebhookDeliveryStatus object. | | [WebhookReceiver](/reference/objects/WebhookReceiver) | The WebhookReceiver object. | | [WebhookReceiverList](/reference/objects/WebhookReceiverList) | The WebhookReceiverList object. | | [WebhookReceiverWithSecret](/reference/objects/WebhookReceiverWithSecret) | The WebhookReceiverWithSecret object. | | [WebhookTest](/reference/objects/WebhookTest) | The WebhookTest object. | | [WhatsappSenderList](/reference/objects/WhatsappSenderList) | The WhatsappSenderList object. | | [WhatsappSenderObject](/reference/objects/WhatsappSenderObject) | A WhatsApp number of the organization's, and the agent that answers it. | | [WhatsappTemplateChoice](/reference/objects/WhatsappTemplateChoice) | The WhatsappTemplateChoice object. | | [WhatsappTemplateList](/reference/objects/WhatsappTemplateList) | The WhatsappTemplateList object. | | [WhatsappTemplateObject](/reference/objects/WhatsappTemplateObject) | A message template Meta has approved for the number's business account. | --- # Agent > The Agent object. | Field | Type | Description | |---|---|---| | `channels` | array of string | Where people can reach it. One of: `voice`, `chat`, `phone`, `whatsapp`. New words may be added. | | `created_at` | string (date-time) | | | `description` | string | | | `direction` | string | Whether it answers or calls. One of: `inbound`, `outbound`. New words may be added. | | `id` | string (uuid) | | | `kind` | string | What the agent is built to do. One of: `form_filling`, `workflow`, `faq`, `custom`, `desk`. New words may be added. | | `name` | string | | | `object` | `agent` | | | `project_id` | string (uuid) | | | `published_at` | string (date-time) or null | | | `status` | string | Only a published agent places calls. One of: `draft`, `published`, `archived`. New words may be added. | | `updated_at` | string (date-time) | | --- # AgentDefinition > An agent as a document: everything about how it behaves, and everything outside it by name An agent as a document: everything about how it behaves, and everything outside it by name. The console's own export format, so a file exported from one and a definition read from the other are the same thing. No credential, no id of another object, no phone number and no domain travels in it: tools, knowledge bases, a calendar and a callback agent are named in `references` and bound by name where the definition lands. | Field | Type | Description | |---|---|---| | `agent` | object | Its name, kind, direction, channels, prompt, configuration, voice, languages, analysis and knowledge settings. | | `exported_at` | string (date-time) | | | `format` | string | The document's version, `agently.agent/1`. | | `object` | `agent_definition` | | | `references` | object | Everything outside the agent it uses, by name: `tools`, `knowledge_bases`, `calendar`, `callback_agent`, and the knowledge each specialist or language narrows to. | --- # AgentDeleted > The AgentDeleted object. | Field | Type | Description | |---|---|---| | `deleted` | `true` | | | `id` | string (uuid) | | | `object` | `agent` | | | `purges_at` | string (date-time) | When it is gone for good. Until then the console can restore it. | --- # AgentDetail > The AgentDetail object. | Field | Type | Description | |---|---|---| | `analysis_enabled` | boolean | | | `analysis_schema` | object | JSON Schema for `analysis`. | | `channels` | array of string | Where people can reach it. One of: `voice`, `chat`, `phone`, `whatsapp`. New words may be added. | | `collected_schema` | object | JSON Schema for `collected`. | | `created_at` | string (date-time) | | | `description` | string | | | `direction` | string | Whether it answers or calls. One of: `inbound`, `outbound`. New words may be added. | | `id` | string (uuid) | | | `kind` | string | What the agent is built to do. One of: `form_filling`, `workflow`, `faq`, `custom`, `desk`. New words may be added. | | `languages` | [Languages](/reference/objects/Languages) | | | `name` | string | | | `object` | `agent` | | | `phone_numbers` | array of [PhoneNumber](/reference/objects/PhoneNumber) | The numbers this agent answers or calls from, in the order a call picks from when it names none. | | `project_id` | string (uuid) | | | `published_at` | string (date-time) or null | | | `status` | string | Only a published agent places calls. One of: `draft`, `published`, `archived`. New words may be added. | | `updated_at` | string (date-time) | | | `variables_schema` | object | JSON Schema for the `variables` a conversation can start with, and its `version`, which changes when the list changes. | --- # AgentDirection > The AgentDirection object. One of: `inbound`, `outbound`. --- # AgentKind > The AgentKind object. One of: `form_filling`, `workflow`, `faq`, `custom`, `desk`. --- # AgentList > The AgentList object. | Field | Type | Description | |---|---|---| | `data` | array of [Agent](/reference/objects/Agent) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # AgentPublishRequest > The AgentPublishRequest object. | Field | Type | Description | |---|---|---| | `note` | string | What changed, kept with the version. | --- # AgentStatus > The AgentStatus object. One of: `draft`, `published`, `archived`. --- # AgentVersionList > The AgentVersionList object. | Field | Type | Description | |---|---|---| | `data` | array of [AgentVersionObject](/reference/objects/AgentVersionObject) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # AgentVersionObject > One published version of an agent: what pinning a conversation to it gets. One published version of an agent: what pinning a conversation to it gets. | Field | Type | Description | |---|---|---| | `agent_id` | string (uuid) | | | `note` | string | What the person who published it said about it. | | `object` | `agent_version` | | | `published_at` | string (date-time) | | | `variables_schema` | object | What a conversation pinned to this version can start with: the agent's `variables_schema`, as this version had it. | | `version` | integer | Its number: what `agent_version` pins a conversation to. | --- # AgentWritten > The AgentWritten object. | Field | Type | Description | |---|---|---| | `analysis_enabled` | boolean | | | `analysis_schema` | object | JSON Schema for `analysis`. | | `channels` | array of string | Where people can reach it. One of: `voice`, `chat`, `phone`, `whatsapp`. New words may be added. | | `collected_schema` | object | JSON Schema for `collected`. | | `created_at` | string (date-time) | | | `description` | string | | | `direction` | string | Whether it answers or calls. One of: `inbound`, `outbound`. New words may be added. | | `id` | string (uuid) | | | `kind` | string | What the agent is built to do. One of: `form_filling`, `workflow`, `faq`, `custom`, `desk`. New words may be added. | | `languages` | [Languages](/reference/objects/Languages) | | | `name` | string | | | `object` | `agent` | | | `phone_numbers` | array of [PhoneNumber](/reference/objects/PhoneNumber) | The numbers this agent answers or calls from, in the order a call picks from when it names none. | | `project_id` | string (uuid) | | | `published_at` | string (date-time) or null | | | `status` | string | Only a published agent places calls. One of: `draft`, `published`, `archived`. New words may be added. | | `unbound` | array of [UnboundReference](/reference/objects/UnboundReference) | What the definition names that this project has nothing by that name for — each left out, with what the agent does instead. | | `updated_at` | string (date-time) | | | `variables_schema` | object | JSON Schema for the `variables` a conversation can start with, and its `version`, which changes when the list changes. | --- # Analysis > The Analysis object. | Field | Type | Description | |---|---|---| | `criteria` | array of [Criterion](/reference/objects/Criterion) or null | | | `extractions` | object or null | | | `outcome` | string or null | `success`, `partial`, `failure` or `unknown`. | | `outcome_reason` | string or null | | | `sentiment` | string or null | `positive`, `neutral` or `negative`. | | `summary` | string or null | | | `topic` | string or null | | --- # Attachment > The Attachment object. | Field | Type | Description | |---|---|---| | `byte_size` | integer | | | `id` | string (uuid) | | | `mime_type` | string | | | `object` | `attachment` | | --- # AuditActor > The AuditActor object. | Field | Type | Description | |---|---|---| | `email` | string or null | A person's email address, while their account exists. | | `id` | string (uuid) or null | The person's or the key's id. Null for the platform, and for a person whose account has since been deleted. | | `name` | string | Who acted, as they were called when they did it. | | `type` | string | Who acted: `person`, `api_key`, or `platform` for something the platform did itself, such as deleting what its retention period reached. New words may be added. | --- # AuditEvent > One thing somebody did in the organization: in the console, or with an API key. One thing somebody did in the organization: in the console, or with an API key. | Field | Type | Description | |---|---|---| | `action` | string | What was done, like `agent.published` or `api_key.created`. New actions may be added. | | `actor` | [AuditActor](/reference/objects/AuditActor) | | | `created_at` | string (date-time) | | | `id` | string (uuid) | | | `meta` | object | The details the action recorded. | | `names` | object | What the ids in `target` and `meta` are called today, keyed by the id. An id whose object is gone is not here. | | `object` | `audit_event` | | | `target` | string | What it was done to, as `kind:id`, like `agent:8a1f…`. | --- # AuditEventList > The AuditEventList object. | Field | Type | Description | |---|---|---| | `data` | array of [AuditEvent](/reference/objects/AuditEvent) | | | `has_more` | boolean | | | `next_cursor` | string or null | Pass it back as `cursor` for the next page. It comes back on the last page too: keep it, and ask again later for what was done since. | | `object` | `list` | | --- # CallWindow > The hours a call may start in, read in one time zone (`services/calling_hours`). The hours a call may start in, read in one time zone (`services/calling_hours`). | Field | Type | Description | |---|---|---| | `days` | array of one of `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun` | The days of the week calls may start on, there. Every day unless you say. | | `end` | string | When calls stop starting, `HH:MM`, after `start` on the same day. A call already talking is never cut off. | | `start` | string | The earliest a call may start, `HH:MM`. | | `timezone` | string | An IANA time zone — the hours are read there. | --- # Campaign > The Campaign object. | Field | Type | Description | |---|---|---| | `agent_id` | string (uuid) | | | `callbacks` | [CampaignCallbacksObject](/reference/objects/CampaignCallbacksObject) | | | `calling_hours` | [CampaignCallingHoursObject](/reference/objects/CampaignCallingHoursObject) | | | `contacts` | [CampaignCounts](/reference/objects/CampaignCounts) | | | `created_at` | string (date-time) | | | `finished_at` | string (date-time) or null | | | `id` | string (uuid) | | | `livemode` | boolean | | | `name` | string | | | `object` | `campaign` | | | `pacing` | [CampaignPacingObject](/reference/objects/CampaignPacingObject) | | | `paused_reason` | string or null | Why it paused itself, when it did. | | `phone_number_id` | string (uuid) or null | | | `project_id` | string (uuid) | | | `start_at` | string (date-time) or null | When a draft will start by itself. | | `started_at` | string (date-time) or null | | | `status` | string | `draft` until it starts; `running` while it calls; `paused`, by you or because it could not go on — `paused_reason` says which; `completed` once nobody is left to call; `cancelled` if you stopped it. One of: `draft`, `running`, `paused`, `completed`, `cancelled`. New words may be added. | | `voicemail` | [CampaignVoicemailObject](/reference/objects/CampaignVoicemailObject) | | --- # CampaignCallbacks > The CampaignCallbacks object. | Field | Type | Description | |---|---|---| | `allowed` | boolean or null | Whether a person may ask the agent to call back at a time of their own. False unless you say. | | `max_callbacks` | integer or null | How often one person may move their call. 2 unless you say. | | `window_days` | integer or null | How many days after the first call a callback may land. 30 unless you say. | --- # CampaignCallbacksObject > The CampaignCallbacksObject object. | Field | Type | Description | |---|---|---| | `allowed` | boolean | | | `max_callbacks` | integer | | | `window_days` | integer | | --- # CampaignCallingHours > The CampaignCallingHours object. | Field | Type | Description | |---|---|---| | `days` | array of one of `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun` or null | The days calls are made on. Every day unless you say. | | `end_hour` | integer or null | The hour calls stop starting, 1–24, after `start_hour`. 20 unless you say. | | `start_hour` | integer or null | The first hour a call may start, 0–23. 9 unless you say. | --- # CampaignCallingHoursObject > The CampaignCallingHoursObject object. | Field | Type | Description | |---|---|---| | `days` | array of string | | | `end_hour` | integer | | | `start_hour` | integer | | --- # CampaignContact > The CampaignContact object. | Field | Type | Description | |---|---|---| | `attempts` | integer | Calls placed to them so far. | | `callback_at` | string (date-time) or null | A time they asked to be called back at. | | `campaign_id` | string (uuid) | | | `conversation_id` | string (uuid) or null | Their latest conversation. | | `created_at` | string (date-time) | | | `disposition` | string or null | How the latest call ended on the line. One of: `answered`, `no_answer`, `busy`, `declined`, `failed`, `unreachable`, `voicemail`, `voicemail_left`. New words may be added. | | `error` | string or null | Why the platform did not call them, when it did not. | | `external_id` | string or null | | | `id` | string (uuid) | | | `metadata` | object | | | `next_attempt_at` | string (date-time) or null | When they are next called, if queued. | | `object` | `campaign_contact` | | | `status` | string | `queued` until their turn or their next try; `dialing` on a call; `done` once reached; `exhausted` when every try is used; `failed` when the platform refused to call them. One of: `queued`, `dialing`, `done`, `failed`, `exhausted`. New words may be added. | | `timezone` | string or null | | | `to_number` | string | | | `variables` | object | | --- # CampaignContactCreate > The CampaignContactCreate object. | Field | Type | Description | |---|---|---| | `external_id` | string or null | | | `metadata` | object | Your own data, carried onto every conversation with this person. The agent never sees it. | | `timezone` | string or null | Where this person is, like `America/Chicago`: the calling hours are read there. Leave it out for your organization's own time zone. | | `to_number` | string | The number to call, in international format. | | `variables` | object | This person's values for the agent's `{{placeholders}}`. | --- # CampaignContactList > The CampaignContactList object. | Field | Type | Description | |---|---|---| | `data` | array of [CampaignContact](/reference/objects/CampaignContact) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # CampaignContactStatus > The CampaignContactStatus object. One of: `queued`, `dialing`, `done`, `failed`, `exhausted`. --- # CampaignContactsAdded > The CampaignContactsAdded object. | Field | Type | Description | |---|---|---| | `added` | integer | People added to the list. | | `already_in_campaign` | array of string | Numbers skipped because the campaign already holds them. | | `campaign_id` | string (uuid) | | | `object` | `campaign_contacts_added` | | --- # CampaignCounts > The CampaignCounts object. | Field | Type | Description | |---|---|---| | `dialing` | integer | Being called now. | | `done` | integer | Reached, or a message was left. | | `exhausted` | integer | Every try used without reaching them. | | `failed` | integer | Not called: the platform refused it — `error` says why. | | `queued` | integer | Waiting for their turn, or for their next try. | | `total` | integer | | --- # CampaignList > The CampaignList object. | Field | Type | Description | |---|---|---| | `data` | array of [Campaign](/reference/objects/Campaign) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # CampaignPacing > The CampaignPacing object. | Field | Type | Description | |---|---|---| | `dials_per_minute` | integer or null | New calls a minute, at most. 20 unless you say. | | `max_attempts` | integer or null | Tries for each person — a busy line, no answer — before they are left alone. 3 unless you say. | | `max_concurrent` | integer or null | Calls at the same time, at most. 5 unless you say. | | `retry_backoff_minutes` | array of integer or null | Minutes to wait before each next try, up to a day each. `[5, 30, 120]` unless you say. | --- # CampaignPacingObject > The CampaignPacingObject object. | Field | Type | Description | |---|---|---| | `dials_per_minute` | integer | | | `max_attempts` | integer | | | `max_concurrent` | integer | | | `retry_backoff_minutes` | array of integer | | --- # CampaignResume > The CampaignResume object. | Field | Type | Description | |---|---|---| | `reset_attempts` | boolean | Give everybody not reached so far every try back. A callback somebody booked keeps its time. | --- # CampaignStatus > The CampaignStatus object. One of: `draft`, `running`, `paused`, `completed`, `cancelled`. --- # CampaignVoicemail > The CampaignVoicemail object. | Field | Type | Description | |---|---|---| | `behaviour` | one of `hang_up`, `leave_message` or null | What a call does when an answering machine picks up. `hang_up` unless you say. | | `message` | string or null | What to say onto the machine, with the agent's `{{placeholders}}`. Needed for `leave_message`. | | `retry_after_message` | boolean or null | Keep trying for a person after leaving a message. False unless you say. | --- # CampaignVoicemailObject > The CampaignVoicemailObject object. | Field | Type | Description | |---|---|---| | `behaviour` | string | `hang_up` or `leave_message`. New words may be added. | | `message` | string or null | | | `retry_after_message` | boolean | | --- # Capabilities > What this deployment of Aigently runs — a company's own copy may switch parts off. What this deployment of Aigently runs — a company's own copy may switch parts off. | Field | Type | Description | |---|---|---| | `channels` | array of string | | | `credits_enforced` | boolean | | | `telephony` | boolean | | | `whatsapp` | boolean | | --- # Channel > The Channel object. One of: `voice`, `chat`, `phone`, `whatsapp`. --- # ChatTurn > One exchange: what the agent said back, and where the conversation stands after it. One exchange: what the agent said back, and where the conversation stands after it. | Field | Type | Description | |---|---|---| | `collected` | object | The answers collected so far. | | `conversation_id` | string (uuid) | | | `finished` | boolean | The agent has nothing more to ask. The chat stays open until it is ended. | | `form_complete` | boolean or null | | | `language` | string or null | | | `object` | `chat.turn` | | | `opening` | string or null | The agent's greeting, on the first turn only — show it above the reply. | | `reply` | string | | | `specialist` | string or null | Which of a desk agent's specialists answered. | | `trail` | array of string | The specialists the conversation has passed through. | --- # Contact > The Contact object. | Field | Type | Description | |---|---|---| | `attributes` | object | | | `created_at` | string (date-time) | | | `id` | string (uuid) | | | `name` | string | | | `object` | `contact` | | | `phone` | string | | | `project_id` | string (uuid) | | | `timezone` | string or null | | | `updated_at` | string (date-time) | | --- # ContactDeleted > The ContactDeleted object. | Field | Type | Description | |---|---|---| | `deleted` | `true` | | | `id` | string (uuid) | | | `object` | `contact` | | --- # ContactFields > The ContactFields object. | Field | Type | Description | |---|---|---| | `attributes` | object | What an agent may say about them: its `{{placeholders}}` take these by name. Kept as text. | | `name` | string | What the console calls them. Never spoken. | | `phone` | string | Their number, in international format. | | `timezone` | string or null | Where they are, like `Asia/Riyadh`: a campaign's calling hours are read there. Leave it out for your organization's own. | --- # ContactImported > The ContactImported object. | Field | Type | Description | |---|---|---| | `added` | integer | | | `errors` | array of object | Each row not taken, by its place in `contacts` — the rest were. | | `object` | `contact_import` | | | `project_id` | string (uuid) | | | `skipped` | integer | Numbers already there, left as they were. | | `updated` | integer | | --- # ContactList > The ContactList object. | Field | Type | Description | |---|---|---| | `data` | array of [Contact](/reference/objects/Contact) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # Context > What the context lookup made of an inbound call (§9.2). What the context lookup made of an inbound call (§9.2). | Field | Type | Description | |---|---|---| | `applied_before_first_reply` | boolean or null | Whether the values were in the agent's prompt for its first reply. | | `ms` | integer or null | How long your server took to answer. | | `problems` | array of [ContextProblem](/reference/objects/ContextProblem) | What went wrong, or which values did not fit and were dropped. | | `status` | string | `pending`, `ok`, `timeout`, `bad_status`, `too_large`, `invalid_answer`, `refused`, `failed` or `busy`. Anything but `ok` means the agent answered without the values. | --- # ContextProblem > The ContextProblem object. | Field | Type | Description | |---|---|---| | `code` | string | | | `field` | string | What did not fit, like `variables.visits`; empty when it was the request. | | `message` | string | | --- # Conversation > `docs/plans/public-api-and-sdks.md` §6.4 — built by `services/conversation_object`. `docs/plans/public-api-and-sdks.md` §6.4 — built by `services/conversation_object`. | Field | Type | Description | |---|---|---| | `agent_id` | string (uuid) | | | `agent_version` | integer or null | The newest version of the agent published when the conversation started. | | `analysis` | [Analysis](/reference/objects/Analysis) or null | | | `analysis_status` | string | `disabled`, `pending`, `completed`, `failed` or `skipped`. New words may be added. | | `answered_at` | string (date-time) or null | | | `caller` | string | What the phone network sent as the caller. Anyone can set it. | | `campaign_id` | string (uuid) or null | | | `changed_at` | string (date-time) | | | `channel` | string | Where it happened. One of: `voice`, `chat`, `phone`, `whatsapp`. New words may be added. | | `collected` | object | | | `context` | [Context](/reference/objects/Context) or null | What the context lookup made of this call; null where none ran. | | `direction` | string or null | Phone calls only. One of: `inbound`, `outbound`. New words may be added. | | `disposition` | string or null | What happened on the phone line. One of: `answered`, `no_answer`, `busy`, `declined`, `failed`, `unreachable`, `voicemail`, `voicemail_left`. New words may be added. | | `duration_seconds` | number or null | | | `end_reason` | string | | | `ended_at` | string (date-time) or null | | | `ended_by` | string or null | What ended it. One of: `agent`, `caller`, `system`, `transfer`, `operator`, `failure`, `api`. New words may be added. | | `error` | string | | | `error_code` | string or null | A stable reason a failed conversation failed. | | `external_id` | string or null | Your own id for it, as you sent it. | | `form_complete` | boolean or null | | | `from_number` | string or null | | | `handoff` | [Handoff](/reference/objects/Handoff) or null | | | `id` | string (uuid) | | | `ignored_variables` | array of string | | | `language` | string or null | | | `livemode` | boolean | | | `metadata` | object | | | `mode` | string | `sandbox` is made by a test key, not real. One of: `test`, `live`, `sandbox`. New words may be added. | | `object` | `conversation` | | | `phone_number_id` | string (uuid) or null | | | `project_id` | string (uuid) | | | `recording_status` | string | `none`, `pending` or `available`. | | `revision` | integer | Goes up each time we send an event about it. | | `sip_status_code` | integer or null | | | `started_at` | string (date-time) | | | `status` | string | Where it stands. One of: `pending`, `active`, `completed`, `failed`. New words may be added. | | `to_number` | string or null | | | `turn_count` | integer | | | `variable_sources` | object | | | `variables` | object | | --- # ConversationCommandObject > Something a live call was asked to do. Something a live call was asked to do. | Field | Type | Description | |---|---|---| | `conversation_id` | string (uuid) | | | `created_at` | string (date-time) | | | `error` | string | Why it failed, when it did. | | `id` | string (uuid) | | | `kind` | string | `say`, `note` or `transfer`. New words may be added. | | `object` | `conversation_command` | | | `status` | string | `sent`, `taken` when the call's agent has it, then `done` or `failed`. New words may be added. | | `updated_at` | string (date-time) | | --- # ConversationList > The ConversationList object. | Field | Type | Description | |---|---|---| | `data` | array of [ConversationListItem](/reference/objects/ConversationListItem) | | | `has_more` | boolean | | | `next_cursor` | string or null | Pass it back as `cursor` for the next page. With `order=changed` it comes back on the last page too: keep it, and ask again later for what changed since. | | `object` | `list` | | --- # ConversationListItem > A conversation as the list returns it A conversation as the list returns it. Only a search adds anything, so `match` lives here and not on `Conversation`, which every other answer and every event embeds. | Field | Type | Description | |---|---|---| | `agent_id` | string (uuid) | | | `agent_version` | integer or null | The newest version of the agent published when the conversation started. | | `analysis` | [Analysis](/reference/objects/Analysis) or null | | | `analysis_status` | string | `disabled`, `pending`, `completed`, `failed` or `skipped`. New words may be added. | | `answered_at` | string (date-time) or null | | | `caller` | string | What the phone network sent as the caller. Anyone can set it. | | `campaign_id` | string (uuid) or null | | | `changed_at` | string (date-time) | | | `channel` | string | Where it happened. One of: `voice`, `chat`, `phone`, `whatsapp`. New words may be added. | | `collected` | object | | | `context` | [Context](/reference/objects/Context) or null | What the context lookup made of this call; null where none ran. | | `direction` | string or null | Phone calls only. One of: `inbound`, `outbound`. New words may be added. | | `disposition` | string or null | What happened on the phone line. One of: `answered`, `no_answer`, `busy`, `declined`, `failed`, `unreachable`, `voicemail`, `voicemail_left`. New words may be added. | | `duration_seconds` | number or null | | | `end_reason` | string | | | `ended_at` | string (date-time) or null | | | `ended_by` | string or null | What ended it. One of: `agent`, `caller`, `system`, `transfer`, `operator`, `failure`, `api`. New words may be added. | | `error` | string | | | `error_code` | string or null | A stable reason a failed conversation failed. | | `external_id` | string or null | Your own id for it, as you sent it. | | `form_complete` | boolean or null | | | `from_number` | string or null | | | `handoff` | [Handoff](/reference/objects/Handoff) or null | | | `id` | string (uuid) | | | `ignored_variables` | array of string | | | `language` | string or null | | | `livemode` | boolean | | | `match` | string or null | Only with `q`: the passage that matched, as plain text. | | `metadata` | object | | | `mode` | string | `sandbox` is made by a test key, not real. One of: `test`, `live`, `sandbox`. New words may be added. | | `object` | `conversation` | | | `phone_number_id` | string (uuid) or null | | | `project_id` | string (uuid) | | | `recording_status` | string | `none`, `pending` or `available`. | | `revision` | integer | Goes up each time we send an event about it. | | `sip_status_code` | integer or null | | | `started_at` | string (date-time) | | | `status` | string | Where it stands. One of: `pending`, `active`, `completed`, `failed`. New words may be added. | | `to_number` | string or null | | | `turn_count` | integer | | | `variable_sources` | object | | | `variables` | object | | --- # ConversationMode > The ConversationMode object. One of: `test`, `live`, `sandbox`. --- # ConversationStatus > The ConversationStatus object. One of: `pending`, `active`, `completed`, `failed`. --- # ConversationWithTranscript > The ConversationWithTranscript object. | Field | Type | Description | |---|---|---| | `agent_id` | string (uuid) | | | `agent_version` | integer or null | The newest version of the agent published when the conversation started. | | `analysis` | [Analysis](/reference/objects/Analysis) or null | | | `analysis_status` | string | `disabled`, `pending`, `completed`, `failed` or `skipped`. New words may be added. | | `answered_at` | string (date-time) or null | | | `caller` | string | What the phone network sent as the caller. Anyone can set it. | | `campaign_id` | string (uuid) or null | | | `changed_at` | string (date-time) | | | `channel` | string | Where it happened. One of: `voice`, `chat`, `phone`, `whatsapp`. New words may be added. | | `collected` | object | | | `context` | [Context](/reference/objects/Context) or null | What the context lookup made of this call; null where none ran. | | `cost` | [Cost](/reference/objects/Cost) or null | Only with `include=cost`, which needs `billing:read`. | | `direction` | string or null | Phone calls only. One of: `inbound`, `outbound`. New words may be added. | | `disposition` | string or null | What happened on the phone line. One of: `answered`, `no_answer`, `busy`, `declined`, `failed`, `unreachable`, `voicemail`, `voicemail_left`. New words may be added. | | `duration_seconds` | number or null | | | `end_reason` | string | | | `ended_at` | string (date-time) or null | | | `ended_by` | string or null | What ended it. One of: `agent`, `caller`, `system`, `transfer`, `operator`, `failure`, `api`. New words may be added. | | `error` | string | | | `error_code` | string or null | A stable reason a failed conversation failed. | | `external_id` | string or null | Your own id for it, as you sent it. | | `form_complete` | boolean or null | | | `from_number` | string or null | | | `handoff` | [Handoff](/reference/objects/Handoff) or null | | | `id` | string (uuid) | | | `ignored_variables` | array of string | | | `language` | string or null | | | `livemode` | boolean | | | `metadata` | object | | | `mode` | string | `sandbox` is made by a test key, not real. One of: `test`, `live`, `sandbox`. New words may be added. | | `object` | `conversation` | | | `phone_number_id` | string (uuid) or null | | | `project_id` | string (uuid) | | | `recording_status` | string | `none`, `pending` or `available`. | | `revision` | integer | Goes up each time we send an event about it. | | `sip_status_code` | integer or null | | | `started_at` | string (date-time) | | | `status` | string | Where it stands. One of: `pending`, `active`, `completed`, `failed`. New words may be added. | | `to_number` | string or null | | | `transcript` | [Transcript](/reference/objects/Transcript) or null | Only with `include=transcript`. | | `turn_count` | integer | | | `variable_sources` | object | | | `variables` | object | | --- # Cost > The Cost object. | Field | Type | Description | |---|---|---| | `credits` | number | What the conversation cost, in credits: its own charge and every analysis of it, less any refund. A test key's chats cost what their model used; its calls cost nothing. | --- # CreditBalance > The CreditBalance object. | Field | Type | Description | |---|---|---| | `available` | number | What can still be spent: the balance, less what conversations in progress hold, plus any credit line. | | `balance` | number | Credit on the account, in credits. | | `enforced` | boolean | Whether running out stops conversations on this deployment. When false, credit is counted and nothing is refused. | | `free_left` | number | How much of the balance is free credit still unspent. | | `object` | `credit_balance` | | | `since` | string (date-time) | | | `spent_this_month` | number | Spent since the first of this month, UTC. | | `suspended` | boolean | New conversations are refused until credit is added. | | `unlimited` | boolean | The organization is never refused for credit. | --- # CreditEntryKind > The CreditEntryKind object. One of: `grant`, `refund`, `removal`, `conversation`, `analysis`, `extraction`, `knowledge`, `evaluation`, `adjustment`. --- # CreditTransaction > The CreditTransaction object. | Field | Type | Description | |---|---|---| | `agent_id` | string (uuid) or null | | | `amount` | number | Credits: positive adds, negative spends. | | `balance_after` | number | | | `conversation_id` | string (uuid) or null | | | `created_at` | string (date-time) | | | `description` | string | | | `id` | string (uuid) | | | `kind` | string | What moved credit. Spending it: `conversation`, `analysis`, `extraction`, `knowledge`, `evaluation`. Adding it: `grant`, `refund`. Corrections: `removal`, `adjustment`. More kinds may be added. | | `livemode` | boolean | False for what a test key spent. | | `object` | `credit_transaction` | | | `project_id` | string (uuid) or null | | --- # CreditTransactionList > The CreditTransactionList object. | Field | Type | Description | |---|---|---| | `data` | array of [CreditTransaction](/reference/objects/CreditTransaction) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # Criterion > The Criterion object. | Field | Type | Description | |---|---|---| | `id` | string | | | `met` | boolean or null | | | `text` | string | | --- # Deleted > The Deleted object. | Field | Type | Description | |---|---|---| | `deleted` | `true` | | | `id` | string (uuid) | | | `object` | string | | --- # DeletedConversation > The DeletedConversation object. | Field | Type | Description | |---|---|---| | `agent_id` | string (uuid) | | | `deleted_at` | string (date-time) | | | `id` | string (uuid) | | | `object` | `deleted_conversation` | | | `project_id` | string (uuid) | | | `reason` | string | Why it was deleted. One of: `retention`, `console`, `agent_deleted`, `project_deleted`, `api`. New words may be added. | --- # DeletedConversationList > The DeletedConversationList object. | Field | Type | Description | |---|---|---| | `data` | array of [DeletedConversation](/reference/objects/DeletedConversation) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # Direction > The Direction object. One of: `inbound`, `outbound`. --- # Disposition > The Disposition object. One of: `answered`, `no_answer`, `busy`, `declined`, `failed`, `unreachable`, `voicemail`, `voicemail_left`. --- # DoNotCallEntry > The DoNotCallEntry object. | Field | Type | Description | |---|---|---| | `added_by` | string | Who listed it: a person, or an API key by name. | | `created_at` | string (date-time) | | | `last_refused_at` | string (date-time) or null | | | `number` | string | In international form, like `+12025550100`. | | `object` | `do_not_call_entry` | | | `reason` | string | Why it was listed, as whoever listed it put it. | | `refused_calls` | integer | Calls refused because it is listed. | --- # DoNotCallList > The DoNotCallList object. | Field | Type | Description | |---|---|---| | `data` | array of [DoNotCallEntry](/reference/objects/DoNotCallEntry) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # DoNotCallRemoved > The DoNotCallRemoved object. | Field | Type | Description | |---|---|---| | `deleted` | `true` | | | `number` | string | | | `object` | `do_not_call_entry` | | --- # EndedBy > The EndedBy object. One of: `agent`, `caller`, `system`, `transfer`, `operator`, `failure`, `api`. --- # EvaluationExpectation > The EvaluationExpectation object. | Field | Type | Description | |---|---|---| | `id` | string | Its name, unique in the evaluation. | | `text` | string | What must be true of the agent's replies. | --- # EvaluationExpectationCreate > The EvaluationExpectationCreate object. | Field | Type | Description | |---|---|---| | `id` | string | Its name, unique in the evaluation. | | `text` | string | What must be true. | --- # EvaluationLatest > The EvaluationLatest object. | Field | Type | Description | |---|---|---| | `error` | string | Why it was not checked, when it was not. | | `outcome` | string | `passed`, `failed`, or `not_checked` when it could not be rehearsed — which says nothing about the agent. New words may be added. | | `rehearsed_at` | string (date-time) | | | `verdicts` | array of [EvaluationVerdict](/reference/objects/EvaluationVerdict) | | --- # EvaluationList > The EvaluationList object. | Field | Type | Description | |---|---|---| | `data` | array of [EvaluationObject](/reference/objects/EvaluationObject) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # EvaluationObject > A saved conversation: what a caller says, and what must be true of the agent's replies. A saved conversation: what a caller says, and what must be true of the agent's replies. | Field | Type | Description | |---|---|---| | `agent_id` | string (uuid) | | | `created_at` | string (date-time) | | | `expectations` | array of [EvaluationExpectation](/reference/objects/EvaluationExpectation) | | | `id` | string (uuid) | | | `latest_result` | [EvaluationLatest](/reference/objects/EvaluationLatest) or null | Its most recent rehearsal — from the console, from publishing or from the API — or null before the first. | | `name` | string | | | `object` | `evaluation` | | | `turns` | array of string | What the caller says, in order. | --- # EvaluationResult > The EvaluationResult object. | Field | Type | Description | |---|---|---| | `error` | string | Why it was not checked, when it was not. | | `evaluation_id` | string (uuid) | | | `name` | string | | | `outcome` | string | `passed`, `failed`, or `not_checked` when it could not be rehearsed — which says nothing about the agent. New words may be added. | | `transcript` | array of [EvaluationTurn](/reference/objects/EvaluationTurn) | The rehearsal, both halves. | | `verdicts` | array of [EvaluationVerdict](/reference/objects/EvaluationVerdict) | One per expectation. | --- # EvaluationRunObject > One rehearsal of every saved conversation an agent has. One rehearsal of every saved conversation an agent has. | Field | Type | Description | |---|---|---| | `agent_id` | string (uuid) | | | `created_at` | string (date-time) | | | `error` | string | Why nothing was rehearsed, when nothing was. | | `failed` | integer | | | `finished_at` | string (date-time) or null | | | `id` | string (uuid) | | | `not_checked` | integer | | | `object` | `evaluation_run` | | | `passed` | integer | | | `results` | array of [EvaluationResult](/reference/objects/EvaluationResult) | Every saved conversation's outcome, once the run is finished. | | `started_at` | string (date-time) or null | | | `status` | string | `queued`, `running` or `finished`. Ask again until it is `finished`. New words may be added. | --- # EvaluationTurn > The EvaluationTurn object. | Field | Type | Description | |---|---|---| | `role` | string | `user` for what the caller said, `assistant` for the agent. | | `text` | string | | --- # EvaluationVerdict > The EvaluationVerdict object. | Field | Type | Description | |---|---|---| | `id` | string | The expectation it judges. | | `met` | boolean | | | `why` | string | The judge's reason, in one sentence. | --- # Event > One event, as a webhook receiver was sent it — under the same id. One event, as a webhook receiver was sent it — under the same id. | Field | Type | Description | |---|---|---| | `created_at` | string (date-time) | | | `data` | object | What a receiver was sent: the conversation, for an event about one. | | `event` | string | Its type, like `conversation.ended`. | | `id` | string (uuid) | The event's id, which every delivery of it carries too. | | `livemode` | boolean | False for an event about what a test key made. | | `object` | `event` | | | `revision` | integer or null | The conversation's revision when this event was made, for an event about one. Of two copies of a conversation, keep the higher. | --- # EventList > The EventList object. | Field | Type | Description | |---|---|---| | `data` | array of [Event](/reference/objects/Event) | | | `has_more` | boolean | | | `next_cursor` | string or null | Pass it back as `cursor` for the next page. It comes back on the last page too: keep it, and ask again later for what happened since. | | `object` | `list` | | --- # Handoff > The Handoff object. | Field | Type | Description | |---|---|---| | `contact` | string or null | | | `destination` | string or null | | | `requested_at` | string (date-time) or null | | | `status` | string or null | | | `summary` | string or null | | --- # Include > The Include object. One of: `transcript`, `cost`. --- # KnowledgeBaseList > The KnowledgeBaseList object. | Field | Type | Description | |---|---|---| | `data` | array of [KnowledgeBaseObject](/reference/objects/KnowledgeBaseObject) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # KnowledgeBaseObject > The KnowledgeBaseObject object. | Field | Type | Description | |---|---|---| | `created_at` | string (date-time) | | | `description` | string | | | `id` | string (uuid) | | | `name` | string | | | `object` | `knowledge_base` | | | `project_id` | string (uuid) | | | `sources` | integer | Files, website pages and topics in it. | | `updated_at` | string (date-time) | | --- # KnowledgeCrawl > The KnowledgeCrawl object. | Field | Type | Description | |---|---|---| | `created_at` | string (date-time) | | | `error` | string or null | | | `id` | string (uuid) | | | `knowledge_base_id` | string (uuid) | | | `last_run_at` | string (date-time) or null | | | `max_pages` | integer | | | `next_run_at` | string (date-time) or null | | | `object` | `knowledge_crawl` | | | `pages_added` | integer | | | `refresh_days` | integer | Read again every this many days; 0 for never. | | `status` | string | How far its latest reading got. One of: `pending`, `crawling`, `awaiting_review`, `completed`, `failed`, `cancelled`. New words may be added. | | `url` | string | | --- # KnowledgeCrawlList > The KnowledgeCrawlList object. | Field | Type | Description | |---|---|---| | `data` | array of [KnowledgeCrawl](/reference/objects/KnowledgeCrawl) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # KnowledgeDocument > The KnowledgeDocument object. | Field | Type | Description | |---|---|---| | `created_at` | string (date-time) | | | `error` | string or null | | | `expires_at` | string (date-time) or null | When it stops being used, if it ever does. | | `filename` | string | | | `id` | string (uuid) | | | `items` | integer | How many pieces of it agents can find. | | `kind` | string | `file` for a file sent to it; `url` for a page of a website it read; `topic` and `faq` for what was written in the console. One of: `file`, `faq`, `topic`, `url`. New words may be added. | | `knowledge_base_id` | string (uuid) | | | `object` | `knowledge_document` | | | `size_bytes` | integer | | | `source_url` | string or null | The page, for a source a website gave it. | | `status` | string | `pending` until the indexer takes it, `processing` while it reads it, `indexed` once agents answer from it, `failed` when it could not — `error` says why — and `held` for a website page waiting for review in the console. One of: `pending`, `processing`, `indexed`, `failed`, `held`. New words may be added. | | `updated_at` | string (date-time) | | --- # KnowledgeDocumentDeleted > The KnowledgeDocumentDeleted object. | Field | Type | Description | |---|---|---| | `deleted` | `true` | | | `id` | string (uuid) | | | `object` | `knowledge_document` | | --- # KnowledgeDocumentList > The KnowledgeDocumentList object. | Field | Type | Description | |---|---|---| | `data` | array of [KnowledgeDocument](/reference/objects/KnowledgeDocument) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # KnowledgeDocumentStatus > The KnowledgeDocumentStatus object. One of: `pending`, `processing`, `indexed`, `failed`, `held`. --- # Language > The Language object. | Field | Type | Description | |---|---|---| | `code` | string | | | `label` | string | | --- # Languages > The Languages object. | Field | Type | Description | |---|---|---| | `auto_detect` | boolean | | | `available` | array of [Language](/reference/objects/Language) | Each language this agent speaks besides its base one. Send its `code` as `language` to use it. | | `default` | string or null | The language used when a conversation asks for none. | --- # Limits > Every ceiling that applies to this key, and how much of the calls one is in use now. Every ceiling that applies to this key, and how much of the calls one is in use now. | Field | Type | Description | |---|---|---| | `calls_at_once` | integer | | | `calls_in_progress` | integer or null | | | `calls_per_day` | integer | | | `calls_per_minute` | integer | | | `reads_per_minute` | integer | | | `writes_per_minute` | integer | | --- # LiveLineObject > One line of a call, as it was said. One line of a call, as it was said. | Field | Type | Description | |---|---|---| | `at` | string (date-time) | | | `object` | `live_line` | | | `role` | string | `user` for the caller, `assistant` for the agent. | | `seq` | integer | Its place in the call, from 1. Send the last one back as `after`. | | `text` | string | | --- # LiveTranscript > What was said on a call since `after`, as it is said. What was said on a call since `after`, as it is said. | Field | Type | Description | |---|---|---| | `conversation_id` | string (uuid) | | | `ended` | boolean | Whether the call has ended and every line it reported has been read: stop asking, and read the conversation's transcript for the record. | | `lines` | array of [LiveLineObject](/reference/objects/LiveLineObject) | | | `next_after` | integer | Send this back as `after` to read only what follows. | | `object` | `live_transcript` | | | `status` | string | The conversation's status, as on the conversation. | --- # McpServerList > The McpServerList object. | Field | Type | Description | |---|---|---| | `data` | array of [McpServerObject](/reference/objects/McpServerObject) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # McpServerObject > One remote MCP server whose tools an agent can be given. One remote MCP server whose tools an agent can be given. | Field | Type | Description | |---|---|---| | `allowed_tools` | array of string or null | Only these of its tools; null for all. | | `auth_key_id` | string (uuid) or null | The vault credential sent with each request. | | `created_at` | string (date-time) | | | `id` | string (uuid) | | | `name` | string | The first half of every tool name the model is shown from it. | | `object` | `mcp_server` | | | `project_id` | string (uuid) | | | `timeout_ms` | integer | | | `url` | string | Its address, with the path and query hidden: a hosted server's path is often its credential. | --- # Me > The Me object. | Field | Type | Description | |---|---|---| | `capabilities` | [Capabilities](/reference/objects/Capabilities) | What this deployment of Aigently runs — a company's own copy may switch parts off. | | `daily_call_limit` | integer or null | | | `id` | string (uuid) | | | `limits` | [Limits](/reference/objects/Limits) | Every ceiling that applies to this key, and how much of the calls one is in use now. | | `mode` | one of `live`, `test` | | | `name` | string | | | `object` | `api_key` | | | `organization` | [OrganizationRef](/reference/objects/OrganizationRef) | | | `permissions` | array of string | | | `reach` | [Reach](/reference/objects/Reach) | | --- # Order > The Order object. One of: `newest`, `oldest`, `changed`. --- # OrganizationRef > The OrganizationRef object. | Field | Type | Description | |---|---|---| | `id` | string (uuid) | | | `name` | string | | --- # Outcome > The Outcome object. One of: `success`, `partial`, `failure`, `unknown`. --- # PhoneNumber > The PhoneNumber object. | Field | Type | Description | |---|---|---| | `agent_id` | string (uuid) or null | The agent this number belongs to: it answers when the number is called. | | `can_place_calls` | boolean | Whether an agent may call from this number — `phone_number_id` on a call. | | `can_receive_calls` | boolean | | | `created_at` | string (date-time) | | | `direction` | string | Which way it carries calls. One of: `inbound`, `outbound`, `both`. New words may be added. | | `id` | string (uuid) | | | `number` | string | The number in international format, like `+966112345678`. | | `object` | `phone_number` | | | `project_id` | string (uuid) | | | `status` | string | Whether it is in service. One of: `active`, `disabled`. New words may be added. | --- # PhoneNumberList > The PhoneNumberList object. | Field | Type | Description | |---|---|---| | `data` | array of [PhoneNumber](/reference/objects/PhoneNumber) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # Problem > RFC 9457 problem details — what every `/v1` error answers with. RFC 9457 problem details — what every `/v1` error answers with. | Field | Type | Description | |---|---|---| | `code` | string | | | `detail` | string | | | `errors` | array of object or null | | | `request_id` | string | | | `status` | integer | | | `title` | string | | | `type` | string | | --- # Project > The Project object. | Field | Type | Description | |---|---|---| | `created_at` | string (date-time) | | | `description` | string | | | `frozen` | boolean | | | `id` | string (uuid) | | | `name` | string | | | `object` | `project` | | --- # ProjectList > The ProjectList object. | Field | Type | Description | |---|---|---| | `data` | array of [Project](/reference/objects/Project) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # Reach > The Reach object. | Field | Type | Description | |---|---|---| | `addresses` | array of string | The address ranges the key works from, in CIDR form. Empty: anywhere. | | `agent_ids` | array of string (uuid) | | | `all_projects` | boolean | | | `project_ids` | array of string (uuid) | | --- # Recording > The Recording object. | Field | Type | Description | |---|---|---| | `audio_channels` | object | Who is on each channel of the stereo file: the caller left, the agent right. | | `content_type` | string | | | `conversation_id` | string (uuid) | | | `duration_seconds` | number or null | | | `expires_at` | string (date-time) | | | `object` | `recording` | | | `url` | string | A link to the audio. It stops working at `expires_at`. | --- # Removed > The Removed object. | Field | Type | Description | |---|---|---| | `deleted` | `true` | | | `id` | string (uuid) | | | `object` | string | | --- # ScheduledCall > The ScheduledCall object. | Field | Type | Description | |---|---|---| | `agent_id` | string (uuid) | | | `agent_version` | integer or null | The published version it will be answered with, when the request pinned one. | | `call_window` | [CallWindow](/reference/objects/CallWindow) or null | | | `conversation_id` | string (uuid) or null | The conversation, once it is placed. | | `created_at` | string (date-time) | | | `dial_at` | string (date-time) | When it will be placed — already moved into its window, if it has one. | | `error` | string or null | | | `error_code` | string or null | Why it was refused at its time — the code `POST /v1/calls` would answer. | | `external_id` | string or null | | | `finished_at` | string (date-time) or null | | | `from_number_id` | string (uuid) or null | | | `id` | string (uuid) | | | `language` | string or null | | | `livemode` | boolean | | | `metadata` | object | | | `object` | `scheduled_call` | | | `project_id` | string (uuid) | | | `status` | string | `scheduled` until its time; `placed` once it became a conversation; `cancelled` if you called it off; `failed` if it was refused at its time. One of: `scheduled`, `placed`, `cancelled`, `failed`. New words may be added. | | `to_number` | string | | | `variables` | object | | --- # ScheduledCallList > The ScheduledCallList object. | Field | Type | Description | |---|---|---| | `data` | array of [ScheduledCall](/reference/objects/ScheduledCall) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # ScheduledCallStatus > The ScheduledCallStatus object. One of: `scheduled`, `placed`, `cancelled`, `failed`. --- # TestInboundCall > The TestInboundCall object. | Field | Type | Description | |---|---|---| | `conversation` | [Conversation](/reference/objects/Conversation) | `docs/plans/public-api-and-sdks.md` §6.4 — built by `services/conversation_object`. | | `lookup` | [TestLookup](/reference/objects/TestLookup) | What the agent's context lookup made of a test call. | | `object` | `test_inbound_call` | | --- # TestLookup > What the agent's context lookup made of a test call. What the agent's context lookup made of a test call. | Field | Type | Description | |---|---|---| | `accepted` | object | The values the agent will use. | | `greeting` | string | The agent's opening line, with the values in it. | | `ignored` | array of string | Names it sent that this agent never uses. | | `ms` | integer or null | | | `problems` | array of [ContextProblem](/reference/objects/ContextProblem) | | | `source` | one of `listen`, `test_address`, `sample`, `none` | Where the answer came from: your machine through `aigently listen`, the test address, the sample answer on the agent's Phone settings, or nowhere — the agent has no lookup. | | `status` | string or null | As `context.status`; null with no lookup. | --- # ToolList > The ToolList object. | Field | Type | Description | |---|---|---| | `data` | array of [ToolObject](/reference/objects/ToolObject) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # ToolObject > One tool: an HTTP request an agent can make mid-conversation, described for its model. One tool: an HTTP request an agent can make mid-conversation, described for its model. | Field | Type | Description | |---|---|---| | `agent_count` | integer | How many agents carry it: who an edit reaches. | | `created_at` | string (date-time) | | | `description` | string | What the model is told it does. | | `http` | object | The request: `method`, `url` (with `{slots}` the model fills), `headers`, `auth` and `timeout_ms`. Header values are hidden: keep secrets in the vault and name them in `auth`. | | `id` | string (uuid) | | | `name` | string | What the model calls it. | | `object` | `tool` | | | `parameters` | object | The JSON Schema of what the model sends it. | | `project_id` | string (uuid) | | | `speaking_hint` | string | Said on a call while it runs, if the model does not. | --- # Transcript > The Transcript object. | Field | Type | Description | |---|---|---| | `conversation_id` | string (uuid) | | | `entries` | array of [TranscriptEntry](/reference/objects/TranscriptEntry) | | | `object` | `transcript` | | | `truncated` | boolean | Whether a long chat's oldest lines were dropped. | --- # TranscriptEntry > The TranscriptEntry object. | Field | Type | Description | |---|---|---| | `arguments` | object or null | | | `at` | string (date-time) or null | | | `confidence` | number or null | | | `elapsed_ms` | integer or null | | | `index` | integer | | | `interrupted` | boolean or null | | | `kind` | string or null | What a note is about. | | `name` | string or null | A tool's name. | | `offset_seconds` | number or null | Where the line falls in the recording. | | `role` | string | `user`, `assistant`, `tool` or `note`. | | `status` | string or null | How a tool call went. | | `text` | string or null | | --- # UnboundReference > The UnboundReference object. | Field | Type | Description | |---|---|---| | `consequence` | string | What the agent does without it. | | `kind` | string | `tool`, `MCP server`, `knowledge base`, `calendar`, `callback agent` or `voice setting`, in the console's own words. New words may be added. | | `name` | string | | --- # VaultSecretList > The VaultSecretList object. | Field | Type | Description | |---|---|---| | `data` | array of [VaultSecretObject](/reference/objects/VaultSecretObject) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # VaultSecretObject > A tool credential in the vault A tool credential in the vault. Its value is never sent back, by anything. | Field | Type | Description | |---|---|---| | `bound_hosts` | array of string | Where it may be sent: pinned by its first use. Only an owner, in the console, sends it somewhere new. | | `created_at` | string (date-time) | | | `id` | string (uuid) | | | `last_four` | string | Its last four characters, to tell two apart. | | `name` | string | | | `object` | `vault_secret` | | | `project_ids` | array of string (uuid) | The projects whose tools may send it. | | `provider` | string | Your own label for whose credential it is. | | `status` | string | `active`, or `revoked`. New words may be added. | --- # WebCall > The WebCall object. | Field | Type | Description | |---|---|---| | `conversation` | [Conversation](/reference/objects/Conversation) | `docs/plans/public-api-and-sdks.md` §6.4 — built by `services/conversation_object`. | | `expires_at` | string (date-time) | | | `object` | `web_call` | | | `token` | string | Joins this one call, from the page, for 15 minutes. Give it to the page that will talk, and to nobody else. | | `url` | string | The voice service's address, for the page to join. | --- # WebhookDelivery > The WebhookDelivery object. | Field | Type | Description | |---|---|---| | `attempts` | integer | | | `created_at` | string (date-time) | | | `delivered_at` | string (date-time) or null | | | `event` | string | | | `event_id` | string (uuid) or null | The event's id, as the event feed lists it. | | `id` | string (uuid) | | | `last_error` | string | Why the last attempt failed, when it did. | | `next_attempt_at` | string (date-time) or null | When it is tried next, while pending. | | `object` | `webhook_delivery` | | | `status` | string | `pending`, `delivered` or `failed`. | --- # WebhookDeliveryList > The WebhookDeliveryList object. | Field | Type | Description | |---|---|---| | `data` | array of [WebhookDelivery](/reference/objects/WebhookDelivery) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # WebhookDeliveryStatus > The WebhookDeliveryStatus object. One of: `pending`, `delivered`, `failed`. --- # WebhookReceiver > The WebhookReceiver object. | Field | Type | Description | |---|---|---| | `agent_ids` | array of string (uuid) | Empty is every agent in the project. | | `created_at` | string (date-time) | | | `enabled` | boolean | | | `events` | array of string | | | `id` | string (uuid) | | | `include_values` | boolean | | | `livemode` | boolean | A live receiver hears real conversations; a test one, only what test keys made. | | `object` | `webhook_receiver` | | | `previous_secret_expires_at` | string (date-time) or null | While a rotated secret's predecessor still signs beside it, when it stops. | | `project_id` | string (uuid) | | | `url` | string | | --- # WebhookReceiverList > The WebhookReceiverList object. | Field | Type | Description | |---|---|---| | `data` | array of [WebhookReceiver](/reference/objects/WebhookReceiver) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # WebhookReceiverWithSecret > The WebhookReceiverWithSecret object. | Field | Type | Description | |---|---|---| | `agent_ids` | array of string (uuid) | Empty is every agent in the project. | | `created_at` | string (date-time) | | | `enabled` | boolean | | | `events` | array of string | | | `id` | string (uuid) | | | `include_values` | boolean | | | `livemode` | boolean | A live receiver hears real conversations; a test one, only what test keys made. | | `object` | `webhook_receiver` | | | `previous_secret_expires_at` | string (date-time) or null | While a rotated secret's predecessor still signs beside it, when it stops. | | `project_id` | string (uuid) | | | `secret` | string | The signing secret. Shown when the receiver is made and when its secret is changed, and never again. | | `url` | string | | --- # WebhookTest > The WebhookTest object. | Field | Type | Description | |---|---|---| | `detail` | string | `delivered`, or why it was not. | | `object` | `webhook_test` | | | `ok` | boolean | | --- # WhatsappSenderList > The WhatsappSenderList object. | Field | Type | Description | |---|---|---| | `data` | array of [WhatsappSenderObject](/reference/objects/WhatsappSenderObject) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # WhatsappSenderObject > A WhatsApp number of the organization's, and the agent that answers it. A WhatsApp number of the organization's, and the agent that answers it. | Field | Type | Description | |---|---|---| | `agent_id` | string (uuid) or null | The agent that answers it; null for none. | | `created_at` | string (date-time) | | | `display_number` | string | | | `id` | string (uuid) | | | `label` | string | | | `object` | `whatsapp_sender` | | | `project_id` | string (uuid) | | | `status` | string | `active` or `disabled`. New words may be added. | --- # WhatsappTemplateChoice > The WhatsappTemplateChoice object. | Field | Type | Description | |---|---|---| | `language` | string | Like `en_US` or `ar`. | | `name` | string | As approved in WhatsApp Manager. | | `parameters` | array of string | The values for its places, in order: `{{1}}` first. | --- # WhatsappTemplateList > The WhatsappTemplateList object. | Field | Type | Description | |---|---|---| | `data` | array of [WhatsappTemplateObject](/reference/objects/WhatsappTemplateObject) | | | `has_more` | boolean | | | `next_cursor` | string or null | | | `object` | `list` | | --- # WhatsappTemplateObject > A message template Meta has approved for the number's business account. A message template Meta has approved for the number's business account. | Field | Type | Description | |---|---|---| | `body` | string | Its words, with `{{1}}`-style places for the values. | | `category` | string | `marketing`, `utility` or `authentication`, as Meta says. | | `language` | string | Its language code, like `en_US` or `ar`. | | `name` | string | | | `object` | `whatsapp_template` | | | `parameters` | integer | How many values it takes, in order. | --- # Errors > Every error code the API answers with, and what to do about it. An error is a problem document (RFC 9457), sent as `application/problem+json`: ```json { "type": "https://developers.aigently.ai/errors/invalid_variables", "title": "The variables do not fit this agent", "status": 422, "code": "invalid_variables", "detail": "1 variable is missing or invalid.", "errors": [ { "field": "variables.first_name", "code": "required", "message": "Required" } ], "request_id": "a3f9c1e07b2d4c4e" } ``` Program against `code`, which never changes. `detail` is a sentence for a person and may be reworded; `errors` names each field a validation failure found. Quote `request_id` when you ask for help — it is also in every response's `X-Request-ID` header. | Status | Code | Means | |---|---|---| | `400` | [`idempotency_key_required`](/errors/idempotency_key_required) | An Idempotency-Key header is required | | `400` | [`invalid_request`](/errors/invalid_request) | The request is not valid | | `401` | [`authentication_failed`](/errors/authentication_failed) | The API key was not accepted | | `402` | [`insufficient_credit`](/errors/insufficient_credit) | There is not enough credit | | `403` | [`address_not_allowed`](/errors/address_not_allowed) | The key does not work from this address | | `403` | [`live_key_in_browser`](/errors/live_key_in_browser) | A live key was sent from a browser | | `403` | [`live_key_required`](/errors/live_key_required) | Only a live key does this | | `403` | [`organization_frozen`](/errors/organization_frozen) | The organization is frozen | | `403` | [`permission_denied`](/errors/permission_denied) | This key does not have that permission | | `403` | [`test_key_required`](/errors/test_key_required) | Only a test key does this | | `404` | [`not_found`](/errors/not_found) | Not found | | `405` | [`method_not_allowed`](/errors/method_not_allowed) | That method is not allowed here | | `409` | [`agent_name_taken`](/errors/agent_name_taken) | The project already has an agent with that name | | `409` | [`agent_not_inbound`](/errors/agent_not_inbound) | The agent does not answer calls | | `409` | [`agent_not_outbound`](/errors/agent_not_outbound) | The agent does not place calls | | `409` | [`agent_not_publishable`](/errors/agent_not_publishable) | The agent is not ready to publish | | `409` | [`agent_not_published`](/errors/agent_not_published) | The agent is not published | | `409` | [`browser_voice_off`](/errors/browser_voice_off) | The agent does not take browser calls | | `409` | [`campaign_empty`](/errors/campaign_empty) | The campaign has nobody to call | | `409` | [`campaign_finished`](/errors/campaign_finished) | The campaign has finished | | `409` | [`campaign_status_conflict`](/errors/campaign_status_conflict) | The campaign is not in a state this applies to | | `409` | [`contact_exists`](/errors/contact_exists) | The number is already in the phonebook | | `409` | [`contacts_missing_values`](/errors/contacts_missing_values) | Contacts lack a value the agent says out loud | | `409` | [`conversation_busy`](/errors/conversation_busy) | The agent is still answering the last message | | `409` | [`conversation_ended`](/errors/conversation_ended) | The conversation has ended | | `409` | [`conversation_in_progress`](/errors/conversation_in_progress) | The conversation is still in progress | | `409` | [`conversation_limit_reached`](/errors/conversation_limit_reached) | The conversation has reached its length | | `409` | [`conversation_not_answered`](/errors/conversation_not_answered) | The call has not been answered yet | | `409` | [`crawl_running`](/errors/crawl_running) | The website is being read | | `409` | [`credential_revoked`](/errors/credential_revoked) | The credential is revoked | | `409` | [`do_not_call`](/errors/do_not_call) | The number is on the do-not-call list | | `409` | [`duplicate_source`](/errors/duplicate_source) | The file is already in the knowledge base | | `409` | [`evaluation_limit_reached`](/errors/evaluation_limit_reached) | The agent has as many evaluations as it can keep | | `409` | [`evaluation_run_in_progress`](/errors/evaluation_run_in_progress) | An evaluation run is already going | | `409` | [`name_taken`](/errors/name_taken) | That name is taken | | `409` | [`not_a_file`](/errors/not_a_file) | The source is not a file | | `409` | [`number_agent_mismatch`](/errors/number_agent_mismatch) | The number and the agent do not fit | | `409` | [`outside_call_window`](/errors/outside_call_window) | The call's window is closed | | `409` | [`project_frozen`](/errors/project_frozen) | The project is frozen | | `409` | [`scheduled_call_finished`](/errors/scheduled_call_finished) | The scheduled call has already happened | | `409` | [`scheduled_call_placing`](/errors/scheduled_call_placing) | The scheduled call is being placed | | `409` | [`source_indexing`](/errors/source_indexing) | The source is being indexed | | `409` | [`transfer_already_requested`](/errors/transfer_already_requested) | The call is already being transferred | | `409` | [`unsupported_channel`](/errors/unsupported_channel) | Not possible on this channel | | `409` | [`whatsapp_not_ready`](/errors/whatsapp_not_ready) | The WhatsApp connection cannot send templates yet | | `413` | [`file_too_large`](/errors/file_too_large) | The file is too large | | `413` | [`request_too_large`](/errors/request_too_large) | The request is too large | | `415` | [`unsupported_file_type`](/errors/unsupported_file_type) | Not a file the knowledge base reads | | `422` | [`caller_id_unavailable`](/errors/caller_id_unavailable) | There is no number to call from | | `422` | [`conversation_too_short`](/errors/conversation_too_short) | The conversation is too short to analyse | | `422` | [`destination_not_allowed`](/errors/destination_not_allowed) | That number cannot be called | | `422` | [`idempotency_key_reused`](/errors/idempotency_key_reused) | The Idempotency-Key was used for a different request | | `422` | [`invalid_variables`](/errors/invalid_variables) | The variables do not fit this agent | | `422` | [`model_misconfigured`](/errors/model_misconfigured) | The agent's model is set up wrongly | | `422` | [`source_limit_reached`](/errors/source_limit_reached) | The knowledge base is full | | `422` | [`test_number_required`](/errors/test_number_required) | Test keys can only call test numbers | | `422` | [`unknown_agent_version`](/errors/unknown_agent_version) | The agent has no such version | | `422` | [`unknown_field`](/errors/unknown_field) | The request has a field this endpoint does not take | | `422` | [`validation_failed`](/errors/validation_failed) | The request did not pass validation | | `424` | [`provider_key_missing`](/errors/provider_key_missing) | A provider credential is missing | | `429` | [`concurrency_limit_reached`](/errors/concurrency_limit_reached) | Too many calls at once | | `429` | [`daily_limit_reached`](/errors/daily_limit_reached) | The daily call limit is reached | | `429` | [`limits_unavailable`](/errors/limits_unavailable) | Limits cannot be checked just now | | `429` | [`rate_limited`](/errors/rate_limited) | Too many requests | | `500` | [`internal_error`](/errors/internal_error) | Something went wrong on our side | | `501` | [`feature_disabled`](/errors/feature_disabled) | Not available on this deployment | | `502` | [`upstream_unavailable`](/errors/upstream_unavailable) | A service the platform depends on is not answering | --- # An Idempotency-Key header is required > 400 idempotency_key_required Placing a call needs your own id for it in the `Idempotency-Key` header, so a retry never calls anybody twice. ## What to do Send an id built from your own data, like `lead-8812-attempt-2`, up to 120 characters. ## Retrying No: the same request gets the same answer until something is changed. --- # The request is not valid > 400 invalid_request Something about the request itself is wrong: a cursor from another list, an `Idempotency-Key` that is too long, or a combination the endpoint does not take. ## What to do Read `detail`, which names what is wrong, and correct the request. ## Retrying No: the same request gets the same answer until something is changed. --- # The API key was not accepted > 401 authentication_failed The key is missing, mistyped, unknown, revoked or expired. Every one of those gets this same answer, so an error never tells a stranger which keys are real. ## What to do Send `Authorization: Bearer ` with a key from the console's API keys page. A rotated key's old secret stops working when its overlap ends. ## Retrying No: the same request gets the same answer until something is changed. --- # There is not enough credit > 402 insufficient_credit The organization's credit is used up, so nothing new that costs money is started. ## What to do Add credit in the console. Reading conversations keeps working meanwhile. ## Retrying Not until credit is added. --- # The key does not work from this address > 403 address_not_allowed The key was made to work only from certain addresses, and this request came from another. `detail` names the address it came from. ## What to do Call from one of the key's addresses — the API keys page in the console lists them — or make a key that allows this one. ## Retrying No: the same request gets the same answer until something is changed. --- # A live key was sent from a browser > 403 live_key_in_browser A request a browser made — one carrying `Origin` or `Sec-Fetch-Site` — came with a live key. A page anybody can open must never hold a live key, so it is refused even from the developer website. ## What to do Call the API from your server. A test key works from the developer website's Try it. ## Retrying No: the same request gets the same answer until something is changed. --- # Only a live key does this > 403 live_key_required A test key never changes anything real, and this request would: a phone number rings real phones. ## What to do Use a live key, which starts `ag_live_`, from your server. ## Retrying No: the same request gets the same answer until something is changed. --- # The organization is frozen > 403 organization_frozen The organization has been frozen, so its keys can read but change nothing. ## What to do Contact the deployment's operator. ## Retrying No: the same request gets the same answer until something is changed. --- # This key does not have that permission > 403 permission_denied The key works, but was not given the permission this endpoint needs — `detail` names it. ## What to do Make a key with that permission, or add it to this key's preset in the console. ## Retrying No: the same request gets the same answer until something is changed. --- # Only a test key does this > 403 test_key_required Test calls to your agents are made with a test key: a live key's calls are real and come from real phones. ## What to do Use a test key, which starts `ag_test_`. ## Retrying No: the same request gets the same answer until something is changed. --- # Not found > 404 not_found There is no such object for this key. The same answer covers another organization's id, a project or agent outside a limited key's reach, and a real conversation asked for with a test key — a 404 never confirms that an id exists. ## What to do Check the id, and that the key reaches it: its mode, its projects and its agents. ## Retrying No: the same request gets the same answer until something is changed. --- # That method is not allowed here > 405 method_not_allowed The path exists, but not with this HTTP method. ## What to do Check the method against the API reference. ## Retrying No: the same request gets the same answer until something is changed. --- # The project already has an agent with that name > 409 agent_name_taken Agent names are unique within a project. ## What to do Choose another name, or leave `name` out to have the definition's made free. ## Retrying No: the same request gets the same answer until something is changed. --- # The agent does not answer calls > 409 agent_not_inbound A test call has to reach an agent that answers calls; this one places them. ## What to do Use an inbound agent's id. `GET /v1/agents?direction=inbound` lists them. ## Retrying No: the same request gets the same answer until something is changed. --- # The agent does not place calls > 409 agent_not_outbound This agent answers calls; placing them needs one made to call out. ## What to do Use an outbound agent's id. `GET /v1/agents?direction=outbound` lists them. ## Retrying No: the same request gets the same answer until something is changed. --- # The agent is not ready to publish > 409 agent_not_publishable The console's Publish check found something to fix first: a missing prompt, a tool without its credential, a rehearsal that now fails. `errors` lists every reason. ## What to do Fix what `errors` names — in the definition or in the console — and publish again. ## Retrying Not until what `errors` names is fixed. --- # The agent is not published > 409 agent_not_published Only a published agent places calls or chats with people. ## What to do Publish the agent in the console, then send the request again. ## Retrying Not until the agent is published. --- # The agent does not take browser calls > 409 browser_voice_off Browser voice is off among the agent's channels, so nothing can join a call with it from a web page. ## What to do Turn Browser voice on under the agent's channels, on its Configure tab, and publish. ## Retrying No: the same request gets the same answer until something is changed. --- # The campaign has nobody to call > 409 campaign_empty It was told to start with no contacts on its list. A campaign with nobody to call finishes at once, and a finished campaign cannot be given contacts or started again. ## What to do Add its contacts with `POST /v1/campaigns/{id}/contacts`, then start it — or send them in the same request that creates it. ## Retrying No: the same request gets the same answer until something is changed. --- # The campaign has finished > 409 campaign_finished It completed or was cancelled, so it cannot change any more and nobody else on its list is called. ## What to do Create a new campaign for a new list. Its contacts still say how each call went. ## Retrying No: the same request gets the same answer until something is changed. --- # The campaign is not in a state this applies to > 409 campaign_status_conflict Only a running campaign can be paused, and only a paused one resumed. `detail` names the state it is in. ## What to do Read the campaign, then send what applies to it: `start` for a draft, `resume` for a paused campaign. ## Retrying No: the same request gets the same answer until something is changed. --- # The number is already in the phonebook > 409 contact_exists A project's phonebook holds each number once, and this one is there already. ## What to do Find the contact with `GET /v1/contacts?phone=` and change it, or import the list: an import updates the people already there. ## Retrying No: the same request gets the same answer until something is changed. --- # Contacts lack a value the agent says out loud > 409 contacts_missing_values The agent's words use a value that some contacts waiting to be called do not have — usually a placeholder added to the agent after the list was loaded. ## What to do `detail` names the value. Give the agent's field a default, take the placeholder out of its words, or cancel the campaign and create it again with the value for each contact. ## Retrying No: the same request gets the same answer until something is changed. --- # The agent is still answering the last message > 409 conversation_busy A chat takes one message at a time, and the agent has not finished replying to the previous one. ## What to do Wait for the reply before sending the next message. ## Retrying Yes, once the previous reply has arrived. --- # The conversation has ended > 409 conversation_ended A message was sent to a chat that has already ended, or a call that has ended was asked to say something, take a note or transfer. ## What to do Start a new conversation. A call's transcript is the record of what was said. ## Retrying No: the same request gets the same answer until something is changed. --- # The conversation is still in progress > 409 conversation_in_progress A call is deleted, and any conversation analysed, once it has ended — not while somebody is still in it. ## What to do Wait for it to end — `conversation.ended` says when — then send the request again. ## Retrying Yes, once the conversation has ended. --- # The conversation has reached its length > 409 conversation_limit_reached Every chat has a ceiling on its messages, because the whole conversation is sent to the model on every turn. ## What to do Start a new chat. ## Retrying No: the same request gets the same answer until something is changed. --- # The call has not been answered yet > 409 conversation_not_answered A call can be asked to say something, take a note or transfer only once somebody has answered it. ## What to do Wait for `conversation.started`, then send the request again. ## Retrying Yes, once the call is answered. --- # The website is being read > 409 crawl_running This website is being read right now, so there is nothing to start again. ## What to do Read the crawl until it has finished, then ask again if you still need to. ## Retrying Yes, once the reading has finished. --- # The credential is revoked > 409 credential_revoked A revoked credential is kept as a record of what was used, and can never be changed or given to a project again. ## What to do Add a new credential with `POST /v1/vault/secrets`, and point your tools at it. ## Retrying No: the same request gets the same answer until something is changed. --- # The number is on the do-not-call list > 409 do_not_call Your organization listed this number as one its agents must never ring — somebody asked not to be called, or your own system said so. ## What to do Do not call it. If that has changed, remove it from the list — `DELETE /v1/do-not-call/{number}` or the console's Telephony page — and place the call again. ## Retrying No: the same request gets the same answer until something is changed. --- # The file is already in the knowledge base > 409 duplicate_source The same bytes are already a source in this base, and indexing them twice would only repeat what agents find. ## What to do `detail` names the source holding them. Replace that one, or send a different file. ## Retrying No: the same request gets the same answer until something is changed. --- # The agent has as many evaluations as it can keep > 409 evaluation_limit_reached An agent keeps at most 50 saved conversations, because every run rehearses all of them. ## What to do Delete one you no longer need, then add this one. ## Retrying No: the same request gets the same answer until something is changed. --- # An evaluation run is already going > 409 evaluation_run_in_progress Your organization rehearses one agent's saved conversations at a time, from the console or the API. The detail names the run that is going. ## What to do Wait for that run to finish — read it until its `status` is `finished` — then ask again. ## Retrying Yes, once the run that is going has finished. --- # That name is taken > 409 name_taken A tool, an MCP server, a credential or a saved conversation by that name is already there: names are unique in a project, a credential's in the organization, and a saved conversation's in its agent. ## What to do Choose another name, or change the one already there. ## Retrying No: the same request gets the same answer until something is changed. --- # The source is not a file > 409 not_a_file Only a file sent to the knowledge base can be replaced. A website page changes when the website is read again; a topic is written in the console. ## What to do Read the website again with `POST /v1/knowledge-bases/{id}/crawls/{crawl_id}/refresh`. ## Retrying No: the same request gets the same answer until something is changed. --- # The number and the agent do not fit > 409 number_agent_mismatch A number that receives calls rings its agent, so the agent must answer phone calls; a number that only places calls is an outbound agent's caller ID. ## What to do Read `detail`, which says which side to change: the agent, or the number's direction in the console. ## Retrying No: the same request gets the same answer until something is changed. --- # The call's window is closed > 409 outside_call_window The call named the hours it may start in, and this is not one of them. ## What to do `detail` says when the window opens next. Schedule the call for then — `POST /v1/scheduled-calls` with the same window places it at the first moment it is open — or send it again once it is. ## Retrying Yes, once the window is open. --- # The project is frozen > 409 project_frozen The agent's project is frozen, so nothing new starts in it. ## What to do Ask an owner of the organization to unfreeze it in the console. ## Retrying Not until the project is unfrozen. --- # The scheduled call has already happened > 409 scheduled_call_finished It was placed, refused at its time, or cancelled already, so there is nothing left to call off. ## What to do Read it to see what became of it. One placed is a conversation now: end that with `POST /v1/conversations/{id}/end`. ## Retrying No: the same request gets the same answer until something is changed. --- # The scheduled call is being placed > 409 scheduled_call_placing Its time has come and the call is being placed right now, so it can no longer be called off. ## What to do Read it again in a few seconds: once placed, its `conversation_id` names the conversation, and `POST /v1/conversations/{id}/end` ends that. ## Retrying No: the same request gets the same answer until something is changed. --- # The source is being indexed > 409 source_indexing The indexer is reading this source right now, and a second version would race it. ## What to do Read the source until it says `indexed` or `failed`, then send the new version. ## Retrying Yes, once the source has finished indexing. --- # The call is already being transferred > 409 transfer_already_requested A call is transferred once: a transfer has already been asked for, or carried out. ## What to do Read the earlier transfer's command to see how it went. ## Retrying No: the same request gets the same answer until something is changed. --- # Not possible on this channel > 409 unsupported_channel The request does not apply to this conversation's channel — a WhatsApp conversation cannot be ended from here, a call takes no chat messages, only a call has a live transcript, and only a phone call can be transferred. ## What to do Check the conversation's `channel`. ## Retrying No: the same request gets the same answer until something is changed. --- # The WhatsApp connection cannot send templates yet > 409 whatsapp_not_ready Sending a template needs the connection's WhatsApp Business account id and an access token, and one of them is missing. ## What to do Add them on the WhatsApp connection's page in the console, then send the request again. ## Retrying Not until the connection is complete. --- # The file is too large > 413 file_too_large This deployment takes knowledge files up to a set size. `detail` says how large. ## What to do Split the file, or send the parts that matter. ## Retrying No: the same request gets the same answer until something is changed. --- # The request is too large > 413 request_too_large The body is larger than this endpoint accepts. ## What to do Send less: a picture is at most the size the agent accepts, and a JSON body is small. ## Retrying No: the same request gets the same answer until something is changed. --- # Not a file the knowledge base reads > 415 unsupported_file_type A knowledge base reads text, Markdown, CSV, JSON, PDF and Word files, and text must be UTF-8. ## What to do Send one of those types, named with its extension, like `opening-hours.md`. ## Retrying No: the same request gets the same answer until something is changed. --- # There is no number to call from > 422 caller_id_unavailable The agent has no verified number it may call from, or the one named cannot place calls. ## What to do Give the agent a caller ID on its Connect page, or send a `from_number` it holds. ## Retrying No: the same request gets the same answer until something is changed. --- # The conversation is too short to analyse > 422 conversation_too_short Nothing was said in it that an analysis could judge. ## What to do Nothing to do: a conversation this short has no analysis. ## Retrying No: the same request gets the same answer until something is changed. --- # That number cannot be called > 422 destination_not_allowed The number is outside the countries this deployment calls, or is one it never calls. ## What to do Check the number is in international format and in an allowed country. ## Retrying No: the same request gets the same answer until something is changed. --- # The Idempotency-Key was used for a different request > 422 idempotency_key_reused This key already belongs to a conversation started with a different agent, number, values or metadata. ## What to do Use a new key for a new request. The same key is only for sending the same request again. ## Retrying No: the same request gets the same answer until something is changed. --- # The variables do not fit this agent > 422 invalid_variables One or more values are missing, of the wrong type, or outside what the agent accepts. ## What to do `errors` names each one. The agent's `variables_schema` (`GET /v1/agents/{id}`) says what each accepts. ## Retrying No: the same request gets the same answer until something is changed. --- # The agent's model is set up wrongly > 422 model_misconfigured The agent's model refused the request for a reason only its settings can fix. ## What to do Check the agent's model and its credential in the console. ## Retrying No: the same request gets the same answer until something is changed. --- # The knowledge base is full > 422 source_limit_reached A knowledge base holds a set number of sources, and this one holds that many. ## What to do Delete sources it no longer needs, or put this one in another knowledge base. ## Retrying No: the same request gets the same answer until something is changed. --- # Test keys can only call test numbers > 422 test_number_required A test key never rings a real phone, so it may only call — or be called from — one of the test numbers. ## What to do Use a test number from the test mode guide, or a live key for a real call. ## Retrying No: the same request gets the same answer until something is changed. --- # The agent has no such version > 422 unknown_agent_version A conversation can be pinned only to a version the agent was published as. ## What to do `GET /v1/agents/{id}/versions` lists them. Leave `agent_version` out for what is live. ## Retrying No: the same request gets the same answer until something is changed. --- # The request has a field this endpoint does not take > 422 unknown_field Unknown fields are refused, so a typo like `variabels` fails loudly instead of placing a call without its values. ## What to do Remove or correct the field `errors` names. ## Retrying No: the same request gets the same answer until something is changed. --- # The request did not pass validation > 422 validation_failed A field is missing, has the wrong type, or is out of range. ## What to do Each entry in `errors` names a field, a code and a sentence. Correct those fields. ## Retrying No: the same request gets the same answer until something is changed. --- # A provider credential is missing > 424 provider_key_missing The agent uses a provider for which neither the organization nor the deployment has a credential. ## What to do Add the provider's key to the organization's vault in the console. ## Retrying No: the same request gets the same answer until something is changed. --- # Too many calls at once > 429 concurrency_limit_reached The organization already has as many calls in progress as it may. ## What to do Wait for calls to finish before placing more. `GET /v1/me` shows how many are in progress. ## Retrying Not at once: retrying immediately only adds load. Place it once a call has finished. --- # The daily call limit is reached > 429 daily_limit_reached The organization has placed as many calls today as it may, or used today's share of the platform's model account. ## What to do Wait until the limit resets at midnight UTC, or ask for a higher limit. ## Retrying Not today. --- # Limits cannot be checked just now > 429 limits_unavailable Something that costs money could not be counted safely, so it was refused rather than guessed at. ## What to do Send the request again shortly. ## Retrying Yes, after the number of seconds in the `Retry-After` header. --- # Too many requests > 429 rate_limited The key has used up one of its limits for now. The `RateLimit` headers say which and for how long. ## What to do Slow down; spread requests out over the window. ## Retrying Yes, after the number of seconds in the `Retry-After` header. --- # Something went wrong on our side > 500 internal_error The platform failed to handle the request. ## What to do Send it again shortly. If it keeps happening, report it with the `request_id`. ## Retrying Yes, after a short wait, with the same `Idempotency-Key` where the request has one. --- # Not available on this deployment > 501 feature_disabled This deployment does not run the feature the request needs, such as telephony. ## What to do Contact the deployment's operator. ## Retrying No: the same request gets the same answer until something is changed. --- # A service the platform depends on is not answering > 502 upstream_unavailable A model provider or another service behind the platform did not answer. ## What to do Send the request again shortly. ## Retrying Yes, after a short wait, with the same `Idempotency-Key` where the request has one.