Create a secret
Create a secret for the account this agent belongs to. Use for credentials the agent needs at runtime. Secrets are scoped to the account/workspace, not the individual agent.
POST
/
v1
/
agents
/
{agentId}
/
secrets
Create a secret
curl --request POST \
--url https://api.us.poly.ai/v1/agents/{agentId}/secrets \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"name": "<string>",
"value": "<string>",
"description": "<string>"
}
'import requests
url = "https://api.us.poly.ai/v1/agents/{agentId}/secrets"
payload = {
"name": "<string>",
"value": "<string>",
"description": "<string>"
}
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: '<string>', value: '<string>', description: '<string>'})
};
fetch('https://api.us.poly.ai/v1/agents/{agentId}/secrets', 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.us.poly.ai/v1/agents/{agentId}/secrets",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'value' => '<string>',
'description' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-KEY: <api-key>"
],
]);
$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.us.poly.ai/v1/agents/{agentId}/secrets"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"value\": \"<string>\",\n \"description\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
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.post("https://api.us.poly.ai/v1/agents/{agentId}/secrets")
.header("X-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"value\": \"<string>\",\n \"description\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.us.poly.ai/v1/agents/{agentId}/secrets")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"value\": \"<string>\",\n \"description\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"name": "<string>",
"description": "<string>",
"createdAt": "<string>",
"lastUpdated": "<string>"
}Scoping
Secrets belong to the account (workspace) that owns this agent, not the agent itself. Any other agent in the same account can be granted access to the same secret. The
agentId in the path only determines which account the secret is created under and which agent gets initial access; it does not scope lookups.PolyAI does not enforce an expiry on secrets. If you need to rotate credentials on a schedule (e.g. an annual refresh policy), call Update a secret; PolyAI does not track or enforce rotation cadence itself.
Authorizations
Path Parameters
Body
application/json
Last modified on September 2, 2026
Was this page helpful?
⌘I
Create a secret
curl --request POST \
--url https://api.us.poly.ai/v1/agents/{agentId}/secrets \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"name": "<string>",
"value": "<string>",
"description": "<string>"
}
'import requests
url = "https://api.us.poly.ai/v1/agents/{agentId}/secrets"
payload = {
"name": "<string>",
"value": "<string>",
"description": "<string>"
}
headers = {
"X-API-KEY": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-KEY': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: '<string>', value: '<string>', description: '<string>'})
};
fetch('https://api.us.poly.ai/v1/agents/{agentId}/secrets', 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.us.poly.ai/v1/agents/{agentId}/secrets",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => '<string>',
'value' => '<string>',
'description' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-KEY: <api-key>"
],
]);
$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.us.poly.ai/v1/agents/{agentId}/secrets"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"value\": \"<string>\",\n \"description\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-KEY", "<api-key>")
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.post("https://api.us.poly.ai/v1/agents/{agentId}/secrets")
.header("X-API-KEY", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"value\": \"<string>\",\n \"description\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.us.poly.ai/v1/agents/{agentId}/secrets")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"value\": \"<string>\",\n \"description\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"name": "<string>",
"description": "<string>",
"createdAt": "<string>",
"lastUpdated": "<string>"
}
