Create an agent

⚠️

Preview — this feature is being built; the design below is the spec.

POST https://app.syntic.ai/v1/agents

Save a new agent definition: its model, instructions, tools and limits. The new agent starts at version 1 and appears in the Console’s AI Agents area. Writing definitions needs a key created by someone with the Developer role or higher.

For how this fits into a full workflow, see Agent definitions.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer <key>`: a private inference key (`sk_live_...`). See Authentication.
`syntic-beta`	Yes, while in preview	`agents-2026-11-01`. Without it the call fails with `400 beta_required`. See Versioning.
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Up to 255 characters. Retrying with the same key within 24 hours returns the first result instead of creating a duplicate. See Idempotency.

Body parameters

Parameter	Type	Required	Notes
`name`	string	Yes	Unique in the workspace.
`model`	string	Yes	For example `Amara S1.2`.
`instructions`	string	Yes	Up to 100,000 characters.
`description`	string	No	Up to 500 characters.
`tools`	array	No	Default `[]`. Schemas are validated on save.
`tool_policy`	object	No	Default `{"default": "allow"}`. Turning on tools the Console marks as approval-required needs a key created by an Administrator or Owner.
`mcp_servers`	array	No	Default `[]`.
`skills`	array	No	Default `[]`.
`environment_id`	string	No	Default `null`.
`memory_store_ids`	array	No	Default `[]`. Ids must exist in the workspace.
`vault_ids`	array	No	Default `[]`.
`limits`	object	No	Missing fields take workspace defaults.
`metadata`	object	No	Up to 16 string pairs.

Response

201 Created, Content-Type: application/json

{
  "id": "agt_01JC4R8W6Q2N9X3T5V7Y",
  "type": "agent",
  "name": "refund-desk",
  "description": "Handles refund requests from the support inbox.",
  "version": 1,
  "status": "active",
  "model": "Amara S1.2",
  "instructions": "You handle refund requests for Acme Store. Look the order up before answering.",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "lookup_order",
        "description": "Fetch an order by its id.",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string"
            }
          },
          "required": [
            "order_id"
          ]
        }
      }
    }
  ],
  "tool_policy": {
    "default": "allow",
    "require_approval": [
      "issue_refund"
    ]
  },
  "mcp_servers": [],
  "skills": [],
  "environment_id": null,
  "memory_store_ids": [],
  "vault_ids": [],
  "limits": {
    "max_turns": 30,
    "max_output_tokens_per_turn": 4096,
    "session_token_budget": 400000,
    "session_cost_budget_usd": 2.0
  },
  "metadata": {
    "team": "support"
  },
  "created_at": "2026-11-03T09:14:22Z",
  "updated_at": "2026-11-05T16:02:10Z"
}

Field	Type	Description
`id`	string	Starts with `agt_`; the same across versions.
`name`	string	Unique in the workspace: 1 to 64 lowercase letters, digits, `-` and `_`.
`version`	integer	The version this object describes, from `1`.
`status`	string	`active` or `archived`.
`model`	string	A Syntic model name. Unknown names are rejected; there is no fallback here.
`instructions`	string	System instructions, up to 100,000 characters.
`tools`	array	Function tools and built-in tool entries, up to 128.
`tool_policy`	object	`default` (`allow` or `ask`) plus `require_approval` and `deny` lists of tool names.
`mcp_servers`	array	Remote MCP servers; tokens come from a vault by name.
`skills`	array	`{skill_id, version}` entries.
`environment_id`	string or null	Where code tools run; `null` means no code execution.
`memory_store_ids`	array	Memory stores the agent may use.
`vault_ids`	array	Vaults whose secrets tools may use.
`limits`	object	Defaults for every session: `max_turns`, `max_output_tokens_per_turn`, `session_token_budget`, `session_cost_budget_usd`.
`metadata`	object	Up to 16 string pairs.

Examples

curl -sS https://app.syntic.ai/v1/agents \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "syntic-beta: agents-2026-11-01" \
  -H "Idempotency-Key: 8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69" \
  -H "Content-Type: application/json" \
  -d '{
      "name": "refund-desk",
      "model": "Amara S1.2",
      "instructions": "You handle refund requests for Acme Store. Look the order up before answering.",
      "tools": [
        {
          "type": "function",
          "function": {
            "name": "lookup_order",
            "description": "Fetch an order by its id.",
            "parameters": {
              "type": "object",
              "properties": {
                "order_id": {
                  "type": "string"
                }
              },
              "required": [
                "order_id"
              ]
            }
          }
        }
      ],
      "limits": {
        "max_turns": 30
      }
    }'

import os
 
import requests
 
resp = requests.post(
    "https://app.syntic.ai/v1/agents",
    headers={
        "Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}",
        "syntic-beta": "agents-2026-11-01",
        "Idempotency-Key": "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69",
    },
    json={
        "name": "refund-desk",
        "model": "Amara S1.2",
        "instructions": "You handle refund requests for Acme Store. Look the order up before answering.",
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "lookup_order",
                    "description": "Fetch an order by its id.",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "order_id": {
                                "type": "string",
                            },
                        },
                        "required": ["order_id"],
                    },
                },
            },
        ],
        "limits": {
            "max_turns": 30,
        },
    },
    timeout=60,
)
data = resp.json()
if not resp.ok:
    raise RuntimeError(f"{resp.status_code} {data['error']['code']}: {data['error']['message']}")
print(data)

const res = await fetch('https://app.syntic.ai/v1/agents', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNTIC_API_KEY}`,
    'syntic-beta': 'agents-2026-11-01',
    'Idempotency-Key': '8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "refund-desk",
    "model": "Amara S1.2",
    "instructions": "You handle refund requests for Acme Store. Look the order up before answering.",
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_order",
          "description": "Fetch an order by its id.",
          "parameters": {
            "type": "object",
            "properties": {
              "order_id": {
                "type": "string"
              }
            },
            "required": [
              "order_id"
            ]
          }
        }
      }
    ],
    "limits": {
      "max_turns": 30
    }
  }),
})
const data = await res.json()
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`)
console.log(data)

package main
 
import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)
 
func main() {
	body := strings.NewReader(`{
  "name": "refund-desk",
  "model": "Amara S1.2",
  "instructions": "You handle refund requests for Acme Store. Look the order up before answering.",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "lookup_order",
        "description": "Fetch an order by its id.",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string"
            }
          },
          "required": [
            "order_id"
          ]
        }
      }
    }
  ],
  "limits": {
    "max_turns": 30
  }
}`)
	req, err := http.NewRequest("POST", "https://app.syntic.ai/v1/agents", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SYNTIC_API_KEY"))
	req.Header.Set("syntic-beta", "agents-2026-11-01")
	req.Header.Set("Idempotency-Key", "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69")
	req.Header.Set("Content-Type", "application/json")
 
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
 
	out, _ := io.ReadAll(resp.Body)
	if resp.StatusCode >= 300 {
		panic(fmt.Sprintf("%d: %s", resp.StatusCode, out))
	}
	fmt.Println(string(out))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
public class Example {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "name": "refund-desk",
              "model": "Amara S1.2",
              "instructions": "You handle refund requests for Acme Store. Look the order up before answering.",
              "tools": [
                {
                  "type": "function",
                  "function": {
                    "name": "lookup_order",
                    "description": "Fetch an order by its id.",
                    "parameters": {
                      "type": "object",
                      "properties": {
                        "order_id": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "order_id"
                      ]
                    }
                  }
                }
              ],
              "limits": {
                "max_turns": 30
              }
            }
            """;
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://app.syntic.ai/v1/agents"))
            .header("Authorization", "Bearer " + System.getenv("SYNTIC_API_KEY"))
            .header("syntic-beta", "agents-2026-11-01")
            .header("Idempotency-Key", "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69")
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 300) {
            throw new RuntimeException(response.statusCode() + ": " + response.body());
        }
        System.out.println(response.body());
    }
}

using System.Net.Http.Headers;
using System.Text;
 
using var http = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("POST"), "https://app.syntic.ai/v1/agents");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("SYNTIC_API_KEY"));
request.Headers.Add("syntic-beta", "agents-2026-11-01");
request.Headers.Add("Idempotency-Key", "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69");
request.Content = new StringContent("""
    {
      "name": "refund-desk",
      "model": "Amara S1.2",
      "instructions": "You handle refund requests for Acme Store. Look the order up before answering.",
      "tools": [
        {
          "type": "function",
          "function": {
            "name": "lookup_order",
            "description": "Fetch an order by its id.",
            "parameters": {
              "type": "object",
              "properties": {
                "order_id": {
                  "type": "string"
                }
              },
              "required": [
                "order_id"
              ]
            }
          }
        }
      ],
      "limits": {
        "max_turns": 30
      }
    }
    """, Encoding.UTF8, "application/json");
 
using var response = await http.SendAsync(request);
var text = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode) throw new Exception($"{(int)response.StatusCode}: {text}");
Console.WriteLine(text);

<?php
$body = <<<'JSON'
{
  "name": "refund-desk",
  "model": "Amara S1.2",
  "instructions": "You handle refund requests for Acme Store. Look the order up before answering.",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "lookup_order",
        "description": "Fetch an order by its id.",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {
              "type": "string"
            }
          },
          "required": [
            "order_id"
          ]
        }
      }
    }
  ],
  "limits": {
    "max_turns": 30
  }
}
JSON;
 
$ch = curl_init('https://app.syntic.ai/v1/agents');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SYNTIC_API_KEY'),
        'syntic-beta: agents-2026-11-01',
        'Idempotency-Key: 8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
 
if ($status >= 300) {
    throw new RuntimeException("$status: $response");
}
print_r(json_decode($response, true));

require "json"
require "net/http"
require "uri"
 
uri = URI("https://app.syntic.ai/v1/agents")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch('SYNTIC_API_KEY')}"
req["syntic-beta"] = "agents-2026-11-01"
req["Idempotency-Key"] = "8d6f0c1e-4b2a-4a57-9f0e-2f1d3c4b5a69"
req["Content-Type"] = "application/json"
req.body = <<~'JSON'
  {
    "name": "refund-desk",
    "model": "Amara S1.2",
    "instructions": "You handle refund requests for Acme Store. Look the order up before answering.",
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_order",
          "description": "Fetch an order by its id.",
          "parameters": {
            "type": "object",
            "properties": {
              "order_id": {
                "type": "string"
              }
            },
            "required": [
              "order_id"
            ]
          }
        }
      }
    ],
    "limits": {
      "max_turns": 30
    }
  }
JSON
 
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
raise "#{res.code}: #{res.body}" unless res.is_a?(Net::HTTPSuccess)
puts JSON.pretty_generate(JSON.parse(res.body))

Errors

Errors use the error envelope and carry a request_id. Codes specific to this operation:

Status	`type`	`code`	When
400	`invalid_request_error`	`beta_required`	The `syntic-beta` header is missing.
400	`invalid_request_error`	`invalid_name`	Disallowed characters or too long.
400	`invalid_request_error`	`unknown_model`	`model` is not in the catalog.
400	`invalid_request_error`	`invalid_tool_schema`	A tool’s `parameters` is not a valid JSON Schema object, a tool name repeats, or a size limit is exceeded.
400	`invalid_request_error`	`unknown_reference`	A skill, vault, memory store or environment id does not exist in this workspace.
403	`permission_error`	`role_required`	The key’s creator does not hold the role this change needs.
409	`conflict_error`	`name_taken`	Another agent already uses this name.
401	`authentication_error`	`invalid_api_key`	The key is missing, unknown, revoked or expired.
429	`rate_limit_error`	`rate_limited`	Too many requests; wait for `Retry-After`. See Rate-limit headers.

Agents API List agents

Was this page helpful?