Create an agent in the current workspace

Create an agent

curl --request POST \
  --url https://api.onecli.sh/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Claude Assistant",
  "identifier": "claude-assistant",
  "kind": "byo",
  "harness": "<string>",
  "instructions": "<string>",
  "parentIdentifier": "<string>"
}
'

import requests

url = "https://api.onecli.sh/v1/agents"

payload = {
    "name": "Claude Assistant",
    "identifier": "claude-assistant",
    "kind": "byo",
    "harness": "<string>",
    "instructions": "<string>",
    "parentIdentifier": "<string>"
}
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({
    name: 'Claude Assistant',
    identifier: 'claude-assistant',
    kind: 'byo',
    harness: '<string>',
    instructions: '<string>',
    parentIdentifier: '<string>'
  })
};

fetch('https://api.onecli.sh/v1/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.onecli.sh/v1/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([
    'name' => 'Claude Assistant',
    'identifier' => 'claude-assistant',
    'kind' => 'byo',
    'harness' => '<string>',
    'instructions' => '<string>',
    'parentIdentifier' => '<string>'
  ]),
  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.onecli.sh/v1/agents"

	payload := strings.NewReader("{\n  \"name\": \"Claude Assistant\",\n  \"identifier\": \"claude-assistant\",\n  \"kind\": \"byo\",\n  \"harness\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"parentIdentifier\": \"<string>\"\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.onecli.sh/v1/agents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Claude Assistant\",\n  \"identifier\": \"claude-assistant\",\n  \"kind\": \"byo\",\n  \"harness\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"parentIdentifier\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.onecli.sh/v1/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  \"name\": \"Claude Assistant\",\n  \"identifier\": \"claude-assistant\",\n  \"kind\": \"byo\",\n  \"harness\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"parentIdentifier\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "name": "<string>",
  "identifier": "<string>",
  "kind": "byo",
  "harness": "<string>",
  "model": "<string>",
  "instructions": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "llmKeys": [
    "<string>"
  ]
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

POST

agents

Create an agent

curl --request POST \
  --url https://api.onecli.sh/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Claude Assistant",
  "identifier": "claude-assistant",
  "kind": "byo",
  "harness": "<string>",
  "instructions": "<string>",
  "parentIdentifier": "<string>"
}
'

import requests

url = "https://api.onecli.sh/v1/agents"

payload = {
    "name": "Claude Assistant",
    "identifier": "claude-assistant",
    "kind": "byo",
    "harness": "<string>",
    "instructions": "<string>",
    "parentIdentifier": "<string>"
}
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({
    name: 'Claude Assistant',
    identifier: 'claude-assistant',
    kind: 'byo',
    harness: '<string>',
    instructions: '<string>',
    parentIdentifier: '<string>'
  })
};

fetch('https://api.onecli.sh/v1/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.onecli.sh/v1/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([
    'name' => 'Claude Assistant',
    'identifier' => 'claude-assistant',
    'kind' => 'byo',
    'harness' => '<string>',
    'instructions' => '<string>',
    'parentIdentifier' => '<string>'
  ]),
  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.onecli.sh/v1/agents"

	payload := strings.NewReader("{\n  \"name\": \"Claude Assistant\",\n  \"identifier\": \"claude-assistant\",\n  \"kind\": \"byo\",\n  \"harness\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"parentIdentifier\": \"<string>\"\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.onecli.sh/v1/agents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Claude Assistant\",\n  \"identifier\": \"claude-assistant\",\n  \"kind\": \"byo\",\n  \"harness\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"parentIdentifier\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.onecli.sh/v1/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  \"name\": \"Claude Assistant\",\n  \"identifier\": \"claude-assistant\",\n  \"kind\": \"byo\",\n  \"harness\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"parentIdentifier\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "name": "<string>",
  "identifier": "<string>",
  "kind": "byo",
  "harness": "<string>",
  "model": "<string>",
  "instructions": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "llmKeys": [
    "<string>"
  ]
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

{
  "error": "<string>"
}

Creates a new agent. The kind field picks where it runs: byo (the default) runs on your machine and routes through the gateway, while hosted runs in OneCLI. See Coding agents to connect a byo agent. Creates an agent in the current workspace. The identifier must be lowercase alphanumeric with hyphens, starting with a letter or digit (max 50 characters), and unique in the workspace. kind picks the agent’s home: byo (default) runs on your own machine and routes through the gateway; hosted runs in a OneCLI sandbox and needs a runner to be online. harness and instructions apply to hosted agents only. A new agent is attached to every workspace connection, custom secret, and LLM key automatically, so it can work right away; adjust with the Grants endpoints. The response’s llmKeys lists the LLM keys it received — empty means the workspace has none yet. The response omits the access token — read it from GET /agents or regenerate it with POST /agents/{agentId}/regenerate-token. Re-creating an existing identifier answers 409.

Availability: Cloud · Community (self-hosted) · Enterprise (self-hosted)

Authorizations

Authorization

string

header

required

A workspace API key (oc_…) or organization API key (oc_org_…). Workspace-scoped endpoints called with an organization key also need X-Workspace-Id.

Body

application/json

name

string

required

Required string length: 1 - 255

Example:

"Claude Assistant"

identifier

string

required

Pattern: ^[a-z0-9][a-z0-9-]{0,49}$

Example:

"claude-assistant"

kind

enum<string>

default:byo

Available options:

byo,

hosted

harness

string

Hosted agents only. The agent runtime; omit for the default.

instructions

string

Hosted agents only. The agent's standing brief.

Maximum string length: 20000

parentIdentifier

string

deprecated

Accepted for older CLIs that send it on sub-agent creation; ignored by the server.

Pattern: ^[a-z0-9][a-z0-9-]{0,49}$

Response

Agent created

POST /agents response. The access token is not included; read it from GET /agents or mint a new one with POST /agents/{agentId}/regenerate-token.

string

name

string

identifier

string

kind

enum<string>

Available options:

byo,

hosted

harness

string | null

model

string | null

instructions

string | null

createdAt

string<date-time>

llmKeys

string[]

Secret ids of the LLM keys attached to the new agent automatically. Empty means the workspace has no LLM key yet.

Workspace

Organization

Enterprise

Platform

Create an agent in the current workspace

Authorizations

Body

Response