Update agent
curl --request PATCH \
--url https://api.akua.dev/v1/agents/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'if-match: <if-match>' \
--data '
{
"name": "<string>",
"description": "<string>",
"instructions": "<string>",
"capabilities": [],
"ambient": {
"enabled": true,
"triggers": [
{
"trigger_id": "<string>",
"cooldown_seconds": 123,
"relationship_scope": {
"type": "WORKSPACE"
},
"resource_filters": [
{
"type": "<string>",
"id": "<string>"
}
]
}
]
}
}
'import requests
url = "https://api.akua.dev/v1/agents/{id}"
payload = {
"name": "<string>",
"description": "<string>",
"instructions": "<string>",
"capabilities": [],
"ambient": {
"enabled": True,
"triggers": [
{
"trigger_id": "<string>",
"cooldown_seconds": 123,
"relationship_scope": { "type": "WORKSPACE" },
"resource_filters": [
{
"type": "<string>",
"id": "<string>"
}
]
}
]
}
}
headers = {
"if-match": "<if-match>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {
'if-match': '<if-match>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: '<string>',
description: '<string>',
instructions: '<string>',
capabilities: [],
ambient: {
enabled: true,
triggers: [
{
trigger_id: '<string>',
cooldown_seconds: 123,
relationship_scope: {type: 'WORKSPACE'},
resource_filters: [{type: '<string>', id: '<string>'}]
}
]
}
})
};
fetch('https://api.akua.dev/v1/agents/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.akua.dev/v1/agents/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'instructions' => '<string>',
'capabilities' => [
],
'ambient' => [
'enabled' => true,
'triggers' => [
[
'trigger_id' => '<string>',
'cooldown_seconds' => 123,
'relationship_scope' => [
'type' => 'WORKSPACE'
],
'resource_filters' => [
[
'type' => '<string>',
'id' => '<string>'
]
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"if-match: <if-match>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.akua.dev/v1/agents/{id}"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"instructions\": \"<string>\",\n \"capabilities\": [],\n \"ambient\": {\n \"enabled\": true,\n \"triggers\": [\n {\n \"trigger_id\": \"<string>\",\n \"cooldown_seconds\": 123,\n \"relationship_scope\": {\n \"type\": \"WORKSPACE\"\n },\n \"resource_filters\": [\n {\n \"type\": \"<string>\",\n \"id\": \"<string>\"\n }\n ]\n }\n ]\n }\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("if-match", "<if-match>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.akua.dev/v1/agents/{id}")
.header("if-match", "<if-match>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"instructions\": \"<string>\",\n \"capabilities\": [],\n \"ambient\": {\n \"enabled\": true,\n \"triggers\": [\n {\n \"trigger_id\": \"<string>\",\n \"cooldown_seconds\": 123,\n \"relationship_scope\": {\n \"type\": \"WORKSPACE\"\n },\n \"resource_filters\": [\n {\n \"type\": \"<string>\",\n \"id\": \"<string>\"\n }\n ]\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.akua.dev/v1/agents/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["if-match"] = '<if-match>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"instructions\": \"<string>\",\n \"capabilities\": [],\n \"ambient\": {\n \"enabled\": true,\n \"triggers\": [\n {\n \"trigger_id\": \"<string>\",\n \"cooldown_seconds\": 123,\n \"relationship_scope\": {\n \"type\": \"WORKSPACE\"\n },\n \"resource_filters\": [\n {\n \"type\": \"<string>\",\n \"id\": \"<string>\"\n }\n ]\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"workspace_id": "<string>",
"organization_id": "<string>",
"name": "<string>",
"description": "<string>",
"instructions": "<string>",
"capabilities": [],
"ambient": {
"enabled": true,
"triggers": [
{
"trigger_id": "<string>",
"cooldown_seconds": 123,
"relationship_scope": {
"type": "WORKSPACE"
},
"resource_filters": [
{
"type": "<string>",
"id": "<string>"
}
],
"quiet_hours": {
"timezone": "<string>",
"start": "<string>",
"end": "<string>"
}
}
],
"policy": {
"allowed_resource_scopes": [
{
"type": "<string>",
"id": "<string>"
}
],
"max_spend_cents_per_trigger": 1
}
},
"model_policy": {
"default_model": "<string>",
"credential_secret_id": "<string>",
"allowed_models": [
"<string>"
],
"severity_model_overrides": [
{
"model": "<string>"
}
],
"max_budget_cents": 1,
"max_turn_budget_cents": 1
},
"created_by": "<string>",
"usage_summary": {
"provider_cost_cents": 1,
"provider_token_count": 1,
"runtime_compute_seconds": 1,
"runtime_storage_gb_hours": 1,
"mcp_call_count": 1,
"api_call_count": 1,
"ambient_trigger_count": 1
},
"created_at": 1,
"updated_at": 1,
"etag": "<string>"
}{
"success": false,
"errors": [
{
"code": 7002,
"message": "Resource not found",
"path": [
"body",
"name"
],
"metadata": {}
}
],
"result": {}
}{
"success": false,
"errors": [
{
"code": 7002,
"message": "Resource not found",
"path": [
"body",
"name"
],
"metadata": {}
}
],
"result": {}
}{
"success": false,
"errors": [
{
"code": 7002,
"message": "Resource not found",
"path": [
"body",
"name"
],
"metadata": {}
}
],
"result": {}
}{
"success": false,
"errors": [
{
"code": 7002,
"message": "Resource not found",
"path": [
"body",
"name"
],
"metadata": {}
}
],
"result": {}
}{
"success": false,
"errors": [
{
"code": 7002,
"message": "Resource not found",
"path": [
"body",
"name"
],
"metadata": {}
}
],
"result": {}
}{
"success": false,
"errors": [
{
"code": 7002,
"message": "Resource not found",
"path": [
"body",
"name"
],
"metadata": {}
}
],
"result": {}
}Agents
Update agent
Updates mutable agent configuration. Lifecycle state changes use archive.
PATCH
/
agents
/
{id}
Update agent
curl --request PATCH \
--url https://api.akua.dev/v1/agents/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'if-match: <if-match>' \
--data '
{
"name": "<string>",
"description": "<string>",
"instructions": "<string>",
"capabilities": [],
"ambient": {
"enabled": true,
"triggers": [
{
"trigger_id": "<string>",
"cooldown_seconds": 123,
"relationship_scope": {
"type": "WORKSPACE"
},
"resource_filters": [
{
"type": "<string>",
"id": "<string>"
}
]
}
]
}
}
'import requests
url = "https://api.akua.dev/v1/agents/{id}"
payload = {
"name": "<string>",
"description": "<string>",
"instructions": "<string>",
"capabilities": [],
"ambient": {
"enabled": True,
"triggers": [
{
"trigger_id": "<string>",
"cooldown_seconds": 123,
"relationship_scope": { "type": "WORKSPACE" },
"resource_filters": [
{
"type": "<string>",
"id": "<string>"
}
]
}
]
}
}
headers = {
"if-match": "<if-match>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {
'if-match': '<if-match>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: '<string>',
description: '<string>',
instructions: '<string>',
capabilities: [],
ambient: {
enabled: true,
triggers: [
{
trigger_id: '<string>',
cooldown_seconds: 123,
relationship_scope: {type: 'WORKSPACE'},
resource_filters: [{type: '<string>', id: '<string>'}]
}
]
}
})
};
fetch('https://api.akua.dev/v1/agents/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.akua.dev/v1/agents/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'description' => '<string>',
'instructions' => '<string>',
'capabilities' => [
],
'ambient' => [
'enabled' => true,
'triggers' => [
[
'trigger_id' => '<string>',
'cooldown_seconds' => 123,
'relationship_scope' => [
'type' => 'WORKSPACE'
],
'resource_filters' => [
[
'type' => '<string>',
'id' => '<string>'
]
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"if-match: <if-match>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.akua.dev/v1/agents/{id}"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"instructions\": \"<string>\",\n \"capabilities\": [],\n \"ambient\": {\n \"enabled\": true,\n \"triggers\": [\n {\n \"trigger_id\": \"<string>\",\n \"cooldown_seconds\": 123,\n \"relationship_scope\": {\n \"type\": \"WORKSPACE\"\n },\n \"resource_filters\": [\n {\n \"type\": \"<string>\",\n \"id\": \"<string>\"\n }\n ]\n }\n ]\n }\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("if-match", "<if-match>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.akua.dev/v1/agents/{id}")
.header("if-match", "<if-match>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"instructions\": \"<string>\",\n \"capabilities\": [],\n \"ambient\": {\n \"enabled\": true,\n \"triggers\": [\n {\n \"trigger_id\": \"<string>\",\n \"cooldown_seconds\": 123,\n \"relationship_scope\": {\n \"type\": \"WORKSPACE\"\n },\n \"resource_filters\": [\n {\n \"type\": \"<string>\",\n \"id\": \"<string>\"\n }\n ]\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.akua.dev/v1/agents/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["if-match"] = '<if-match>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"instructions\": \"<string>\",\n \"capabilities\": [],\n \"ambient\": {\n \"enabled\": true,\n \"triggers\": [\n {\n \"trigger_id\": \"<string>\",\n \"cooldown_seconds\": 123,\n \"relationship_scope\": {\n \"type\": \"WORKSPACE\"\n },\n \"resource_filters\": [\n {\n \"type\": \"<string>\",\n \"id\": \"<string>\"\n }\n ]\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"workspace_id": "<string>",
"organization_id": "<string>",
"name": "<string>",
"description": "<string>",
"instructions": "<string>",
"capabilities": [],
"ambient": {
"enabled": true,
"triggers": [
{
"trigger_id": "<string>",
"cooldown_seconds": 123,
"relationship_scope": {
"type": "WORKSPACE"
},
"resource_filters": [
{
"type": "<string>",
"id": "<string>"
}
],
"quiet_hours": {
"timezone": "<string>",
"start": "<string>",
"end": "<string>"
}
}
],
"policy": {
"allowed_resource_scopes": [
{
"type": "<string>",
"id": "<string>"
}
],
"max_spend_cents_per_trigger": 1
}
},
"model_policy": {
"default_model": "<string>",
"credential_secret_id": "<string>",
"allowed_models": [
"<string>"
],
"severity_model_overrides": [
{
"model": "<string>"
}
],
"max_budget_cents": 1,
"max_turn_budget_cents": 1
},
"created_by": "<string>",
"usage_summary": {
"provider_cost_cents": 1,
"provider_token_count": 1,
"runtime_compute_seconds": 1,
"runtime_storage_gb_hours": 1,
"mcp_call_count": 1,
"api_call_count": 1,
"ambient_trigger_count": 1
},
"created_at": 1,
"updated_at": 1,
"etag": "<string>"
}{
"success": false,
"errors": [
{
"code": 7002,
"message": "Resource not found",
"path": [
"body",
"name"
],
"metadata": {}
}
],
"result": {}
}{
"success": false,
"errors": [
{
"code": 7002,
"message": "Resource not found",
"path": [
"body",
"name"
],
"metadata": {}
}
],
"result": {}
}{
"success": false,
"errors": [
{
"code": 7002,
"message": "Resource not found",
"path": [
"body",
"name"
],
"metadata": {}
}
],
"result": {}
}{
"success": false,
"errors": [
{
"code": 7002,
"message": "Resource not found",
"path": [
"body",
"name"
],
"metadata": {}
}
],
"result": {}
}{
"success": false,
"errors": [
{
"code": 7002,
"message": "Resource not found",
"path": [
"body",
"name"
],
"metadata": {}
}
],
"result": {}
}{
"success": false,
"errors": [
{
"code": 7002,
"message": "Resource not found",
"path": [
"body",
"name"
],
"metadata": {}
}
],
"result": {}
}Authorizations
workspace API token (sk_akua_...) or OAuth2 JWT. Create tokens at https://akua.dev/developers/api-tokens
Headers
Optional workspace/scope context for the request. Carries a single workspace wire id (ws_…) today. Only needed for broad tokens — a workspace-owned token implies its workspace.
Required string length:
1 - 53Example:
"ws_j572abc123def456"
The etag of the resource version the client last read. Required on writes when the resource exposes an etag field. Mismatch returns 409 ABORTED with the current etag in the error metadata.
Required string length:
1 - 256Example:
"42"
Path Parameters
Required string length:
1 - 54Body
application/json
Required string length:
1 - 120Maximum string length:
500Required string length:
1 - 20000Required array length:
1 - 10 elementsAvailable options:
CHAT, CODING, AMBIENT Show child attributes
Show child attributes
Show child attributes
Show child attributes
Response
Agent updated
Required string length:
1 - 54Required string length:
1 - 53Required string length:
1 - 54Available options:
ENABLED, ARCHIVED Available options:
PLATFORM, USER, SYSTEM Available options:
CHAT, CODING, AMBIENT Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Unix timestamp (seconds)
Required range:
x >= 0Unix timestamp (seconds)
Required range:
x >= 0⌘I