Create agent
curl --request POST \
--url https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/agents \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"profile": "<string>",
"config": "<string>",
"name": "<string>",
"message": "<string>",
"tools": {},
"subscriptions": [
{
"integration_id": "<string>",
"conversation": {}
}
],
"interaction_handlers": {}
}
'import requests
url = "https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/agents"
payload = {
"profile": "<string>",
"config": "<string>",
"name": "<string>",
"message": "<string>",
"tools": {},
"subscriptions": [
{
"integration_id": "<string>",
"conversation": {}
}
],
"interaction_handlers": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
profile: '<string>',
config: '<string>',
name: '<string>',
message: '<string>',
tools: {},
subscriptions: [{integration_id: '<string>', conversation: {}}],
interaction_handlers: {}
})
};
fetch('https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/agents', 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.omnara.com/v1/orgs/{orgID}/projects/{projectID}/agents",
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([
'profile' => '<string>',
'config' => '<string>',
'name' => '<string>',
'message' => '<string>',
'tools' => [
],
'subscriptions' => [
[
'integration_id' => '<string>',
'conversation' => [
]
]
],
'interaction_handlers' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.omnara.com/v1/orgs/{orgID}/projects/{projectID}/agents"
payload := strings.NewReader("{\n \"profile\": \"<string>\",\n \"config\": \"<string>\",\n \"name\": \"<string>\",\n \"message\": \"<string>\",\n \"tools\": {},\n \"subscriptions\": [\n {\n \"integration_id\": \"<string>\",\n \"conversation\": {}\n }\n ],\n \"interaction_handlers\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
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.post("https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/agents")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"profile\": \"<string>\",\n \"config\": \"<string>\",\n \"name\": \"<string>\",\n \"message\": \"<string>\",\n \"tools\": {},\n \"subscriptions\": [\n {\n \"integration_id\": \"<string>\",\n \"conversation\": {}\n }\n ],\n \"interaction_handlers\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"profile\": \"<string>\",\n \"config\": \"<string>\",\n \"name\": \"<string>\",\n \"message\": \"<string>\",\n \"tools\": {},\n \"subscriptions\": [\n {\n \"integration_id\": \"<string>\",\n \"conversation\": {}\n }\n ],\n \"interaction_handlers\": {}\n}"
response = http.request(request)
puts response.read_body{
"agent": {
"id": "<string>",
"org_id": "<string>",
"project_id": "<string>",
"state": "active",
"name": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"agent_profile_id": "<string>",
"integration_target": {
"provider": "<string>",
"conversation": {},
"display_name": "<string>",
"provider_uri": "<string>"
},
"current_config_id": "<string>",
"model": {
"provider_config": "<string>",
"name": "<string>"
},
"parent_agent_id": "<string>",
"subagent_key": "<string>",
"activity": {
"state": "running",
"last_activity_at": "2023-11-07T05:31:56Z"
},
"usage": {
"model_calls": 1,
"tokens": {
"input_tokens_total": 1,
"uncached_input_tokens": 1,
"cache_read_input_tokens": 1,
"cache_write_input_tokens": 1,
"output_tokens_total": 1,
"reasoning_output_tokens": 1
},
"cost": {
"provider_reported_usd": "<string>",
"model_calls_with_reported_cost": 1
}
},
"archived_at": "2023-11-07T05:31:56Z"
}
}{
"agent": {
"id": "<string>",
"org_id": "<string>",
"project_id": "<string>",
"state": "active",
"name": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"agent_profile_id": "<string>",
"integration_target": {
"provider": "<string>",
"conversation": {},
"display_name": "<string>",
"provider_uri": "<string>"
},
"current_config_id": "<string>",
"model": {
"provider_config": "<string>",
"name": "<string>"
},
"parent_agent_id": "<string>",
"subagent_key": "<string>",
"activity": {
"state": "running",
"last_activity_at": "2023-11-07T05:31:56Z"
},
"usage": {
"model_calls": 1,
"tokens": {
"input_tokens_total": 1,
"uncached_input_tokens": 1,
"cache_read_input_tokens": 1,
"cache_write_input_tokens": 1,
"output_tokens_total": 1,
"reasoning_output_tokens": 1
},
"cost": {
"provider_reported_usd": "<string>",
"model_calls_with_reported_cost": 1
}
},
"archived_at": "2023-11-07T05:31:56Z"
},
"agent_config": {
"id": "<string>",
"org_id": "<string>",
"project_id": "<string>",
"effective_definition_hash": "<string>",
"model": {
"provider_config": "<string>",
"name": "<string>",
"provider_model_slug": "<string>",
"configured_model_id": "<string>",
"current_revision_id": "<string>",
"api_format": "openai-responses",
"api_variant": "<string>",
"context_window_tokens": 123,
"max_output_tokens": 123,
"default_cache_retention": "none",
"supports_tools": true,
"supports_reasoning": true,
"default_reasoning_effort": "<string>",
"supported_reasoning_efforts": [
"<string>"
],
"input_modalities": [
"<string>"
],
"output_modalities": [
"<string>"
],
"default_max_output_tokens": 123
},
"created_at": "2023-11-07T05:31:56Z",
"compiled_definition": {
"instruction": "<string>",
"model": {
"configured_model_id": "<string>",
"context_window_tokens": 123,
"default_max_output_tokens": 123,
"cache_retention": "none",
"reasoning": {
"effort": "<string>"
}
},
"version": "<string>",
"machine_sources": [
{
"machine_id": "<string>",
"machine_pool_id": "<string>",
"max_machines": 123,
"initial_num_machines": 123,
"delete_after_idle_minutes": 123,
"cwd": "<string>",
"machine_cpu": 123,
"machine_memory_mb": 123,
"env_overlay": {},
"secret_env_overlay": {},
"machine_provider_options_overlay": {},
"description": "<string>"
}
],
"tools": {},
"mcp": {},
"event_webhook": {
"url": "<string>",
"events": [
"agent_input"
],
"signing_secret_id": "<string>"
},
"interaction_handlers": {},
"git_credentials": {
"integration": "<string>",
"integration_id": "<string>"
},
"skills": [
{
"id": "<string>"
}
],
"memory_stores": [
{
"id": "<string>",
"access": "read"
}
],
"subagents": {},
"max_subagents": 123,
"max_depth": 123
},
"source": "<string>",
"source_format": "yaml",
"instruction_hash": "<string>"
},
"machine_bindings": [
{
"id": "<string>",
"project_id": "<string>",
"agent_id": "<string>",
"machine_id": "<string>",
"binding_kind": "explicit",
"state": "attached",
"description": "<string>",
"cwd": "<string>",
"env_overlay": {},
"secret_env_overlay": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
],
"agent_input": {
"id": "<string>",
"agent_id": "<string>",
"state": "<string>",
"delivery_mode": "queued",
"input_kind": "content",
"queued_at": "2023-11-07T05:31:56Z",
"actor_id": "<string>",
"input_idempotency_key": "<string>",
"content_blocks": [
{
"type": "text",
"text": "<string>",
"metadata": {}
}
]
}
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}Agents
Create agent
Launch from a pinned config, optionally adding agent-local integration tools, subscriptions and interaction handlers and admitting an attributed initial text input in the same transaction. Adding integration capabilities requires project management permission; launching an existing config requires agent operate permission. Reusing an idempotency key returns the current agent even if the retry body differs. The retry body is not applied and integration references are not resolved again.
POST
/
orgs
/
{orgID}
/
projects
/
{projectID}
/
agents
Create agent
curl --request POST \
--url https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/agents \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"profile": "<string>",
"config": "<string>",
"name": "<string>",
"message": "<string>",
"tools": {},
"subscriptions": [
{
"integration_id": "<string>",
"conversation": {}
}
],
"interaction_handlers": {}
}
'import requests
url = "https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/agents"
payload = {
"profile": "<string>",
"config": "<string>",
"name": "<string>",
"message": "<string>",
"tools": {},
"subscriptions": [
{
"integration_id": "<string>",
"conversation": {}
}
],
"interaction_handlers": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
profile: '<string>',
config: '<string>',
name: '<string>',
message: '<string>',
tools: {},
subscriptions: [{integration_id: '<string>', conversation: {}}],
interaction_handlers: {}
})
};
fetch('https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/agents', 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.omnara.com/v1/orgs/{orgID}/projects/{projectID}/agents",
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([
'profile' => '<string>',
'config' => '<string>',
'name' => '<string>',
'message' => '<string>',
'tools' => [
],
'subscriptions' => [
[
'integration_id' => '<string>',
'conversation' => [
]
]
],
'interaction_handlers' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.omnara.com/v1/orgs/{orgID}/projects/{projectID}/agents"
payload := strings.NewReader("{\n \"profile\": \"<string>\",\n \"config\": \"<string>\",\n \"name\": \"<string>\",\n \"message\": \"<string>\",\n \"tools\": {},\n \"subscriptions\": [\n {\n \"integration_id\": \"<string>\",\n \"conversation\": {}\n }\n ],\n \"interaction_handlers\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
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.post("https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/agents")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"profile\": \"<string>\",\n \"config\": \"<string>\",\n \"name\": \"<string>\",\n \"message\": \"<string>\",\n \"tools\": {},\n \"subscriptions\": [\n {\n \"integration_id\": \"<string>\",\n \"conversation\": {}\n }\n ],\n \"interaction_handlers\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.omnara.com/v1/orgs/{orgID}/projects/{projectID}/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"profile\": \"<string>\",\n \"config\": \"<string>\",\n \"name\": \"<string>\",\n \"message\": \"<string>\",\n \"tools\": {},\n \"subscriptions\": [\n {\n \"integration_id\": \"<string>\",\n \"conversation\": {}\n }\n ],\n \"interaction_handlers\": {}\n}"
response = http.request(request)
puts response.read_body{
"agent": {
"id": "<string>",
"org_id": "<string>",
"project_id": "<string>",
"state": "active",
"name": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"agent_profile_id": "<string>",
"integration_target": {
"provider": "<string>",
"conversation": {},
"display_name": "<string>",
"provider_uri": "<string>"
},
"current_config_id": "<string>",
"model": {
"provider_config": "<string>",
"name": "<string>"
},
"parent_agent_id": "<string>",
"subagent_key": "<string>",
"activity": {
"state": "running",
"last_activity_at": "2023-11-07T05:31:56Z"
},
"usage": {
"model_calls": 1,
"tokens": {
"input_tokens_total": 1,
"uncached_input_tokens": 1,
"cache_read_input_tokens": 1,
"cache_write_input_tokens": 1,
"output_tokens_total": 1,
"reasoning_output_tokens": 1
},
"cost": {
"provider_reported_usd": "<string>",
"model_calls_with_reported_cost": 1
}
},
"archived_at": "2023-11-07T05:31:56Z"
}
}{
"agent": {
"id": "<string>",
"org_id": "<string>",
"project_id": "<string>",
"state": "active",
"name": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"agent_profile_id": "<string>",
"integration_target": {
"provider": "<string>",
"conversation": {},
"display_name": "<string>",
"provider_uri": "<string>"
},
"current_config_id": "<string>",
"model": {
"provider_config": "<string>",
"name": "<string>"
},
"parent_agent_id": "<string>",
"subagent_key": "<string>",
"activity": {
"state": "running",
"last_activity_at": "2023-11-07T05:31:56Z"
},
"usage": {
"model_calls": 1,
"tokens": {
"input_tokens_total": 1,
"uncached_input_tokens": 1,
"cache_read_input_tokens": 1,
"cache_write_input_tokens": 1,
"output_tokens_total": 1,
"reasoning_output_tokens": 1
},
"cost": {
"provider_reported_usd": "<string>",
"model_calls_with_reported_cost": 1
}
},
"archived_at": "2023-11-07T05:31:56Z"
},
"agent_config": {
"id": "<string>",
"org_id": "<string>",
"project_id": "<string>",
"effective_definition_hash": "<string>",
"model": {
"provider_config": "<string>",
"name": "<string>",
"provider_model_slug": "<string>",
"configured_model_id": "<string>",
"current_revision_id": "<string>",
"api_format": "openai-responses",
"api_variant": "<string>",
"context_window_tokens": 123,
"max_output_tokens": 123,
"default_cache_retention": "none",
"supports_tools": true,
"supports_reasoning": true,
"default_reasoning_effort": "<string>",
"supported_reasoning_efforts": [
"<string>"
],
"input_modalities": [
"<string>"
],
"output_modalities": [
"<string>"
],
"default_max_output_tokens": 123
},
"created_at": "2023-11-07T05:31:56Z",
"compiled_definition": {
"instruction": "<string>",
"model": {
"configured_model_id": "<string>",
"context_window_tokens": 123,
"default_max_output_tokens": 123,
"cache_retention": "none",
"reasoning": {
"effort": "<string>"
}
},
"version": "<string>",
"machine_sources": [
{
"machine_id": "<string>",
"machine_pool_id": "<string>",
"max_machines": 123,
"initial_num_machines": 123,
"delete_after_idle_minutes": 123,
"cwd": "<string>",
"machine_cpu": 123,
"machine_memory_mb": 123,
"env_overlay": {},
"secret_env_overlay": {},
"machine_provider_options_overlay": {},
"description": "<string>"
}
],
"tools": {},
"mcp": {},
"event_webhook": {
"url": "<string>",
"events": [
"agent_input"
],
"signing_secret_id": "<string>"
},
"interaction_handlers": {},
"git_credentials": {
"integration": "<string>",
"integration_id": "<string>"
},
"skills": [
{
"id": "<string>"
}
],
"memory_stores": [
{
"id": "<string>",
"access": "read"
}
],
"subagents": {},
"max_subagents": 123,
"max_depth": 123
},
"source": "<string>",
"source_format": "yaml",
"instruction_hash": "<string>"
},
"machine_bindings": [
{
"id": "<string>",
"project_id": "<string>",
"agent_id": "<string>",
"machine_id": "<string>",
"binding_kind": "explicit",
"state": "attached",
"description": "<string>",
"cwd": "<string>",
"env_overlay": {},
"secret_env_overlay": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
],
"agent_input": {
"id": "<string>",
"agent_id": "<string>",
"state": "<string>",
"delivery_mode": "queued",
"input_kind": "content",
"queued_at": "2023-11-07T05:31:56Z",
"actor_id": "<string>",
"input_idempotency_key": "<string>",
"content_blocks": [
{
"type": "text",
"text": "<string>",
"metadata": {}
}
]
}
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>",
"current_digest": "<string>",
"issues": [
{
"path": "<string>",
"message": "<string>",
"line": 2,
"column": 2
}
]
}{
"error": "<string>",
"code": "<string>"
}{
"error": "<string>",
"code": "<string>"
}Authorizations
bearerAuthbrowserSessionCookie & csrfHeader
An opaque Omnara personal or organization bearer token.
Headers
Idempotency key for replay-safe mutating requests.
Required string length:
1 - 255Path Parameters
Organization ID (org_...).
Pattern:
^org_[a-z2-7]{26}$Project ID (proj_...).
Pattern:
^proj_[a-z2-7]{26}$Body
application/json
- Option 1
- Option 2
- Option 3
Send at least one of profile, config, or config_source, and not both config and config_source. With only profile, the agent runs the profile's current config. With profile and config or config_source, the agent is attributed to the profile but runs the given config, which need not be one of the profile's versions. config_source is compiled and saved as a new config during the launch.
Pattern:
^aprf_[a-z2-7]{26}$Agent config ID (acfg_...).
Pattern:
^acfg_[a-z2-7]{26}$An agent config to compile. YAML sources are stored verbatim, so comments and formatting survive; JSON sources, as text or as an object, are stored canonicalized, so the same JSON definition always maps to the same config.
Show child attributes
Show child attributes
Optional agent name. Omit to inherit the profile name when present; send an empty string to leave the agent unnamed.
Maximum string length:
64Optional initial text message. Mutually exclusive with initial_input.
Additional integration tool entries (int____) and optional list_interaction_handlers or set_interaction_handler tools for this agent. Other tool names are not accepted here. Existing config entries win unchanged. Requires project management permission. The derived config is created atomically with the agent and initial input; the profile is unchanged.
Show child attributes
Show child attributes
Integration-owned conversation subscriptions attached atomically with launch and initial input. Requires project management permission. Subscriptions alone preserve the pinned config. Launch replay never adds or restores subscriptions.
Maximum array length:
100Show child attributes
Show child attributes
Additional integration interaction handlers, keyed by immutable integration name with empty object values. Slack and Discord handlers require an assigned conversation and accept empty runtime args. Adding a handler does not assign a conversation. Existing entries win unchanged. Requires project management permission.
Show child attributes
Show child attributes
Initial queued text input, committed atomically with the agent and any derived config. Mutually exclusive with message. Initial inline media is not supported; upload it through the agent input endpoint after launch.
Show child attributes
Show child attributes
Response
Current state of the previously created agent.
Show child attributes
Show child attributes