Create task (stream/json)

curl --request POST \
  --url https://neo.api.projectdiscovery.io/api/v1/tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": "<string>",
  "agent_ids": [
    "<string>"
  ],
  "ask_question": false,
  "auto_execute": false,
  "browser_session_refs": [
    "<string>"
  ],
  "credential_ref": "<string>",
  "credits_budget": 500,
  "file_keys": [
    "<string>"
  ],
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "isolated": false,
  "max_duration_seconds": 86400,
  "max_iterations": 2,
  "max_steps": 102,
  "memory_off": false,
  "message": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "parts": [
      {
        "media_type": "<string>",
        "name": "<string>",
        "text": "<string>",
        "url": "<string>"
      }
    ],
    "role": "user"
  },
  "mode": "agent",
  "model": "<string>",
  "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sandbox_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "secrets": [
    "<string>"
  ],
  "subagent_models": [
    "<string>"
  ],
  "subagent_reasoning_effort": "auto",
  "task": "<string>",
  "title": "<string>",
  "tool_review": {
    "fail_closed": true
  }
}
'

import requests

url = "https://neo.api.projectdiscovery.io/api/v1/tasks"

payload = {
    "agent_id": "<string>",
    "agent_ids": ["<string>"],
    "ask_question": False,
    "auto_execute": False,
    "browser_session_refs": ["<string>"],
    "credential_ref": "<string>",
    "credits_budget": 500,
    "file_keys": ["<string>"],
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "isolated": False,
    "max_duration_seconds": 86400,
    "max_iterations": 2,
    "max_steps": 102,
    "memory_off": False,
    "message": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "parts": [
            {
                "media_type": "<string>",
                "name": "<string>",
                "text": "<string>",
                "url": "<string>"
            }
        ],
        "role": "user"
    },
    "mode": "agent",
    "model": "<string>",
    "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "sandbox_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "secrets": ["<string>"],
    "subagent_models": ["<string>"],
    "subagent_reasoning_effort": "auto",
    "task": "<string>",
    "title": "<string>",
    "tool_review": { "fail_closed": True }
}
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({
    agent_id: '<string>',
    agent_ids: ['<string>'],
    ask_question: false,
    auto_execute: false,
    browser_session_refs: ['<string>'],
    credential_ref: '<string>',
    credits_budget: 500,
    file_keys: ['<string>'],
    id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    isolated: false,
    max_duration_seconds: 86400,
    max_iterations: 2,
    max_steps: 102,
    memory_off: false,
    message: {
      id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
      parts: [{media_type: '<string>', name: '<string>', text: '<string>', url: '<string>'}],
      role: 'user'
    },
    mode: 'agent',
    model: '<string>',
    project_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    sandbox_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    secrets: ['<string>'],
    subagent_models: ['<string>'],
    subagent_reasoning_effort: 'auto',
    task: '<string>',
    title: '<string>',
    tool_review: {fail_closed: true}
  })
};

fetch('https://neo.api.projectdiscovery.io/api/v1/tasks', 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://neo.api.projectdiscovery.io/api/v1/tasks",
  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([
    'agent_id' => '<string>',
    'agent_ids' => [
        '<string>'
    ],
    'ask_question' => false,
    'auto_execute' => false,
    'browser_session_refs' => [
        '<string>'
    ],
    'credential_ref' => '<string>',
    'credits_budget' => 500,
    'file_keys' => [
        '<string>'
    ],
    'id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'isolated' => false,
    'max_duration_seconds' => 86400,
    'max_iterations' => 2,
    'max_steps' => 102,
    'memory_off' => false,
    'message' => [
        'id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
        'parts' => [
                [
                                'media_type' => '<string>',
                                'name' => '<string>',
                                'text' => '<string>',
                                'url' => '<string>'
                ]
        ],
        'role' => 'user'
    ],
    'mode' => 'agent',
    'model' => '<string>',
    'project_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'sandbox_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'secrets' => [
        '<string>'
    ],
    'subagent_models' => [
        '<string>'
    ],
    'subagent_reasoning_effort' => 'auto',
    'task' => '<string>',
    'title' => '<string>',
    'tool_review' => [
        'fail_closed' => true
    ]
  ]),
  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://neo.api.projectdiscovery.io/api/v1/tasks"

	payload := strings.NewReader("{\n  \"agent_id\": \"<string>\",\n  \"agent_ids\": [\n    \"<string>\"\n  ],\n  \"ask_question\": false,\n  \"auto_execute\": false,\n  \"browser_session_refs\": [\n    \"<string>\"\n  ],\n  \"credential_ref\": \"<string>\",\n  \"credits_budget\": 500,\n  \"file_keys\": [\n    \"<string>\"\n  ],\n  \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"isolated\": false,\n  \"max_duration_seconds\": 86400,\n  \"max_iterations\": 2,\n  \"max_steps\": 102,\n  \"memory_off\": false,\n  \"message\": {\n    \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n    \"parts\": [\n      {\n        \"media_type\": \"<string>\",\n        \"name\": \"<string>\",\n        \"text\": \"<string>\",\n        \"url\": \"<string>\"\n      }\n    ],\n    \"role\": \"user\"\n  },\n  \"mode\": \"agent\",\n  \"model\": \"<string>\",\n  \"project_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"sandbox_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"secrets\": [\n    \"<string>\"\n  ],\n  \"subagent_models\": [\n    \"<string>\"\n  ],\n  \"subagent_reasoning_effort\": \"auto\",\n  \"task\": \"<string>\",\n  \"title\": \"<string>\",\n  \"tool_review\": {\n    \"fail_closed\": true\n  }\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://neo.api.projectdiscovery.io/api/v1/tasks")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_id\": \"<string>\",\n  \"agent_ids\": [\n    \"<string>\"\n  ],\n  \"ask_question\": false,\n  \"auto_execute\": false,\n  \"browser_session_refs\": [\n    \"<string>\"\n  ],\n  \"credential_ref\": \"<string>\",\n  \"credits_budget\": 500,\n  \"file_keys\": [\n    \"<string>\"\n  ],\n  \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"isolated\": false,\n  \"max_duration_seconds\": 86400,\n  \"max_iterations\": 2,\n  \"max_steps\": 102,\n  \"memory_off\": false,\n  \"message\": {\n    \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n    \"parts\": [\n      {\n        \"media_type\": \"<string>\",\n        \"name\": \"<string>\",\n        \"text\": \"<string>\",\n        \"url\": \"<string>\"\n      }\n    ],\n    \"role\": \"user\"\n  },\n  \"mode\": \"agent\",\n  \"model\": \"<string>\",\n  \"project_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"sandbox_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"secrets\": [\n    \"<string>\"\n  ],\n  \"subagent_models\": [\n    \"<string>\"\n  ],\n  \"subagent_reasoning_effort\": \"auto\",\n  \"task\": \"<string>\",\n  \"title\": \"<string>\",\n  \"tool_review\": {\n    \"fail_closed\": true\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://neo.api.projectdiscovery.io/api/v1/tasks")

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  \"agent_id\": \"<string>\",\n  \"agent_ids\": [\n    \"<string>\"\n  ],\n  \"ask_question\": false,\n  \"auto_execute\": false,\n  \"browser_session_refs\": [\n    \"<string>\"\n  ],\n  \"credential_ref\": \"<string>\",\n  \"credits_budget\": 500,\n  \"file_keys\": [\n    \"<string>\"\n  ],\n  \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"isolated\": false,\n  \"max_duration_seconds\": 86400,\n  \"max_iterations\": 2,\n  \"max_steps\": 102,\n  \"memory_off\": false,\n  \"message\": {\n    \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n    \"parts\": [\n      {\n        \"media_type\": \"<string>\",\n        \"name\": \"<string>\",\n        \"text\": \"<string>\",\n        \"url\": \"<string>\"\n      }\n    ],\n    \"role\": \"user\"\n  },\n  \"mode\": \"agent\",\n  \"model\": \"<string>\",\n  \"project_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"sandbox_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"secrets\": [\n    \"<string>\"\n  ],\n  \"subagent_models\": [\n    \"<string>\"\n  ],\n  \"subagent_reasoning_effort\": \"auto\",\n  \"task\": \"<string>\",\n  \"title\": \"<string>\",\n  \"tool_review\": {\n    \"fail_closed\": true\n  }\n}"

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

<string>

{
  "credits_budget": 123,
  "max_duration_seconds": 123,
  "status": "accepted",
  "task_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "warnings": [
    {
      "code": "spending_cap_approaching",
      "message": "<string>"
    }
  ]
}

{
  "error": "Bad request",
  "code": "user_spending_cap_reached",
  "error_id": "<string>",
  "kind": "forbidden request",
  "message": "<string>",
  "param": "<string>",
  "turnstile_site_key": "<string>"
}

{
  "error": "Bad request",
  "code": "user_spending_cap_reached",
  "error_id": "<string>",
  "kind": "forbidden request",
  "message": "<string>",
  "param": "<string>",
  "turnstile_site_key": "<string>"
}

{
  "error": "Bad request",
  "code": "user_spending_cap_reached",
  "error_id": "<string>",
  "kind": "forbidden request",
  "message": "<string>",
  "param": "<string>",
  "turnstile_site_key": "<string>"
}

Tasks

Create task (stream/json)

Create a new task or continue an existing one. Returns SSE by default, or JSON acknowledgement when requested.

Response Modes:

default (response_format omitted): streaming SSE response (text/event-stream)
response_format=json: synchronous acknowledgement (202 + task id/status JSON)
if response_format is omitted and Accept: application/json is sent, JSON acknowledgement is returned.

Mode Options:

agent (default): Full agent mode with all tools, execution capabilities, and memory
chat: Conversational mode with limited tools (web search, knowledge search)

Direct Agent Execution:

Use agent_id to bypass AgentSwarm and route to a specific agent

Secrets (Opt-In):

Use secrets to pass only selected secret names into task runtime
If omitted, no user/project secrets are exposed by default

Failure codes on a custom endpoint (BYOK): a task that runs on a custom OpenAI-compatible endpoint can end with an error whose message starts with a stable code:

context_window_exceeded: the conversation is longer than the endpoint’s model accepts. Start a new task or pick a model with a larger context window.
custom_endpoint_task_limit: the task reached the step or token cap Neo applies to a custom endpoint (no cost is known for it, so no credit budget stops it). Start a new task to continue.

POST

api

tasks

Create task (stream/json)

curl --request POST \
  --url https://neo.api.projectdiscovery.io/api/v1/tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": "<string>",
  "agent_ids": [
    "<string>"
  ],
  "ask_question": false,
  "auto_execute": false,
  "browser_session_refs": [
    "<string>"
  ],
  "credential_ref": "<string>",
  "credits_budget": 500,
  "file_keys": [
    "<string>"
  ],
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "isolated": false,
  "max_duration_seconds": 86400,
  "max_iterations": 2,
  "max_steps": 102,
  "memory_off": false,
  "message": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "parts": [
      {
        "media_type": "<string>",
        "name": "<string>",
        "text": "<string>",
        "url": "<string>"
      }
    ],
    "role": "user"
  },
  "mode": "agent",
  "model": "<string>",
  "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sandbox_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "secrets": [
    "<string>"
  ],
  "subagent_models": [
    "<string>"
  ],
  "subagent_reasoning_effort": "auto",
  "task": "<string>",
  "title": "<string>",
  "tool_review": {
    "fail_closed": true
  }
}
'

import requests

url = "https://neo.api.projectdiscovery.io/api/v1/tasks"

payload = {
    "agent_id": "<string>",
    "agent_ids": ["<string>"],
    "ask_question": False,
    "auto_execute": False,
    "browser_session_refs": ["<string>"],
    "credential_ref": "<string>",
    "credits_budget": 500,
    "file_keys": ["<string>"],
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "isolated": False,
    "max_duration_seconds": 86400,
    "max_iterations": 2,
    "max_steps": 102,
    "memory_off": False,
    "message": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "parts": [
            {
                "media_type": "<string>",
                "name": "<string>",
                "text": "<string>",
                "url": "<string>"
            }
        ],
        "role": "user"
    },
    "mode": "agent",
    "model": "<string>",
    "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "sandbox_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "secrets": ["<string>"],
    "subagent_models": ["<string>"],
    "subagent_reasoning_effort": "auto",
    "task": "<string>",
    "title": "<string>",
    "tool_review": { "fail_closed": True }
}
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({
    agent_id: '<string>',
    agent_ids: ['<string>'],
    ask_question: false,
    auto_execute: false,
    browser_session_refs: ['<string>'],
    credential_ref: '<string>',
    credits_budget: 500,
    file_keys: ['<string>'],
    id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    isolated: false,
    max_duration_seconds: 86400,
    max_iterations: 2,
    max_steps: 102,
    memory_off: false,
    message: {
      id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
      parts: [{media_type: '<string>', name: '<string>', text: '<string>', url: '<string>'}],
      role: 'user'
    },
    mode: 'agent',
    model: '<string>',
    project_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    sandbox_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    secrets: ['<string>'],
    subagent_models: ['<string>'],
    subagent_reasoning_effort: 'auto',
    task: '<string>',
    title: '<string>',
    tool_review: {fail_closed: true}
  })
};

fetch('https://neo.api.projectdiscovery.io/api/v1/tasks', 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://neo.api.projectdiscovery.io/api/v1/tasks",
  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([
    'agent_id' => '<string>',
    'agent_ids' => [
        '<string>'
    ],
    'ask_question' => false,
    'auto_execute' => false,
    'browser_session_refs' => [
        '<string>'
    ],
    'credential_ref' => '<string>',
    'credits_budget' => 500,
    'file_keys' => [
        '<string>'
    ],
    'id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'isolated' => false,
    'max_duration_seconds' => 86400,
    'max_iterations' => 2,
    'max_steps' => 102,
    'memory_off' => false,
    'message' => [
        'id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
        'parts' => [
                [
                                'media_type' => '<string>',
                                'name' => '<string>',
                                'text' => '<string>',
                                'url' => '<string>'
                ]
        ],
        'role' => 'user'
    ],
    'mode' => 'agent',
    'model' => '<string>',
    'project_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'sandbox_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'secrets' => [
        '<string>'
    ],
    'subagent_models' => [
        '<string>'
    ],
    'subagent_reasoning_effort' => 'auto',
    'task' => '<string>',
    'title' => '<string>',
    'tool_review' => [
        'fail_closed' => true
    ]
  ]),
  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://neo.api.projectdiscovery.io/api/v1/tasks"

	payload := strings.NewReader("{\n  \"agent_id\": \"<string>\",\n  \"agent_ids\": [\n    \"<string>\"\n  ],\n  \"ask_question\": false,\n  \"auto_execute\": false,\n  \"browser_session_refs\": [\n    \"<string>\"\n  ],\n  \"credential_ref\": \"<string>\",\n  \"credits_budget\": 500,\n  \"file_keys\": [\n    \"<string>\"\n  ],\n  \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"isolated\": false,\n  \"max_duration_seconds\": 86400,\n  \"max_iterations\": 2,\n  \"max_steps\": 102,\n  \"memory_off\": false,\n  \"message\": {\n    \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n    \"parts\": [\n      {\n        \"media_type\": \"<string>\",\n        \"name\": \"<string>\",\n        \"text\": \"<string>\",\n        \"url\": \"<string>\"\n      }\n    ],\n    \"role\": \"user\"\n  },\n  \"mode\": \"agent\",\n  \"model\": \"<string>\",\n  \"project_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"sandbox_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"secrets\": [\n    \"<string>\"\n  ],\n  \"subagent_models\": [\n    \"<string>\"\n  ],\n  \"subagent_reasoning_effort\": \"auto\",\n  \"task\": \"<string>\",\n  \"title\": \"<string>\",\n  \"tool_review\": {\n    \"fail_closed\": true\n  }\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://neo.api.projectdiscovery.io/api/v1/tasks")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_id\": \"<string>\",\n  \"agent_ids\": [\n    \"<string>\"\n  ],\n  \"ask_question\": false,\n  \"auto_execute\": false,\n  \"browser_session_refs\": [\n    \"<string>\"\n  ],\n  \"credential_ref\": \"<string>\",\n  \"credits_budget\": 500,\n  \"file_keys\": [\n    \"<string>\"\n  ],\n  \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"isolated\": false,\n  \"max_duration_seconds\": 86400,\n  \"max_iterations\": 2,\n  \"max_steps\": 102,\n  \"memory_off\": false,\n  \"message\": {\n    \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n    \"parts\": [\n      {\n        \"media_type\": \"<string>\",\n        \"name\": \"<string>\",\n        \"text\": \"<string>\",\n        \"url\": \"<string>\"\n      }\n    ],\n    \"role\": \"user\"\n  },\n  \"mode\": \"agent\",\n  \"model\": \"<string>\",\n  \"project_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"sandbox_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"secrets\": [\n    \"<string>\"\n  ],\n  \"subagent_models\": [\n    \"<string>\"\n  ],\n  \"subagent_reasoning_effort\": \"auto\",\n  \"task\": \"<string>\",\n  \"title\": \"<string>\",\n  \"tool_review\": {\n    \"fail_closed\": true\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://neo.api.projectdiscovery.io/api/v1/tasks")

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  \"agent_id\": \"<string>\",\n  \"agent_ids\": [\n    \"<string>\"\n  ],\n  \"ask_question\": false,\n  \"auto_execute\": false,\n  \"browser_session_refs\": [\n    \"<string>\"\n  ],\n  \"credential_ref\": \"<string>\",\n  \"credits_budget\": 500,\n  \"file_keys\": [\n    \"<string>\"\n  ],\n  \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"isolated\": false,\n  \"max_duration_seconds\": 86400,\n  \"max_iterations\": 2,\n  \"max_steps\": 102,\n  \"memory_off\": false,\n  \"message\": {\n    \"id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n    \"parts\": [\n      {\n        \"media_type\": \"<string>\",\n        \"name\": \"<string>\",\n        \"text\": \"<string>\",\n        \"url\": \"<string>\"\n      }\n    ],\n    \"role\": \"user\"\n  },\n  \"mode\": \"agent\",\n  \"model\": \"<string>\",\n  \"project_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"sandbox_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"secrets\": [\n    \"<string>\"\n  ],\n  \"subagent_models\": [\n    \"<string>\"\n  ],\n  \"subagent_reasoning_effort\": \"auto\",\n  \"task\": \"<string>\",\n  \"title\": \"<string>\",\n  \"tool_review\": {\n    \"fail_closed\": true\n  }\n}"

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

<string>

{
  "credits_budget": 123,
  "max_duration_seconds": 123,
  "status": "accepted",
  "task_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "warnings": [
    {
      "code": "spending_cap_approaching",
      "message": "<string>"
    }
  ]
}

{
  "error": "Bad request",
  "code": "user_spending_cap_reached",
  "error_id": "<string>",
  "kind": "forbidden request",
  "message": "<string>",
  "param": "<string>",
  "turnstile_site_key": "<string>"
}

{
  "error": "Bad request",
  "code": "user_spending_cap_reached",
  "error_id": "<string>",
  "kind": "forbidden request",
  "message": "<string>",
  "param": "<string>",
  "turnstile_site_key": "<string>"
}

{
  "error": "Bad request",
  "code": "user_spending_cap_reached",
  "error_id": "<string>",
  "kind": "forbidden request",
  "message": "<string>",
  "param": "<string>",
  "turnstile_site_key": "<string>"
}

Authorizations

Authorization

string

header

required

JWT authentication token

Body

application/json

agent_id

string

Bypass AgentSwarm and route to specific agent

agent_ids

string[]

Array of agent IDs for multi-agent orchestration

ask_question

boolean

default:false

Enable the ask_question tool for the planner with durable DB-backed suspension. When false (default), the tool and its prompt sections are removed entirely so the planner must proceed without asking the user clarifying questions.

auto_execute

boolean

default:false

When mode=plan, auto-execute the plan without waiting for user approval. Omit for goal mode, which is always automatic.

browser_session_refs

string[]

Optional standalone browser session references (brs_) to continue from. With one ref the agent reuses that warm, logged-in browser daemon instead of launching fresh; with multiple, the orchestrator runs one browser subagent per referenced session so each drives its own session. Every ref must exist on the user's sandbox (ownership is validated per ref). Cannot be used with an isolated task.

completion_delivery

enum<string>

Optional. When set, controls how task results are handed off on completion. webhook — POST the completion artifact to the team webhook URL when configured. artifact — persist the completion artifact for GET /api/v1/tasks/{id}/artifacts. When omitted, no completion handoff runs.

Available options:

webhook,

artifact

credential_ref

string

Optional credential that serves the model when several of the account's credentials could, on the BYOK and AI connections model sources. For BYOK it is a provider key ID, a custom endpoint ID (the credential_ref of a GET /api/v1/models row), or a byok: credential reference; for AI connections it is personal or share:<id>. When omitted, a fixed preference applies (a direct vendor key, then Vertex, Bedrock, and the universal gateways, then custom endpoints oldest first) and an AI connection that fails never falls back to a teammate's share. Ignored for the Neo model source.

credits_budget

number<double>

default:500

Maximum Neo credits this execution may consume.

Required range: 1 <= x <= 500

file_keys

string[]

Optional file references

string<uuid>

Optional task ID. If omitted or invalid, server generates one.

isolated

boolean

default:false

Run task in an ephemeral sandbox with no prior user context

max_duration_seconds

integer

default:86400

Maximum cumulative active runtime; approval suspension time is excluded.

Required range: 300 <= x <= 86400

max_iterations

integer

Max execution-verification loop iterations for agent/plan modes. Goal mode has a fixed 10-run ceiling and rejects this field. When omitted, defaults to 0 for agent mode (no verification) and 1 for plan mode (single execute + verify cycle). 0 = explicitly skip verification. 1+ = run that many execute+verify cycles.

Required range: 0 <= x <= 5

max_steps

integer

Max LLM steps for execution mode only. Goal mode uses the fixed swarm ceiling of 60 and rejects this field. Does not affect plan or verification phases. Defaults to 45 (direct) or 60 (swarm).

Required range: 4 <= x <= 200

memory_off

boolean

default:false

Disable use of memory from previous tasks for this run. Current-task working memory remains available, while personal, team, and learned project memory are not read or updated. Explicit recall of another task is also blocked.

message

object

Show child attributes

mode

enum<string>

default:agent

agent = full tools, chat = limited tools, plan = info-gathering + strategic planning, goal = plan once then autonomously execute and verify until complete

Available options:

agent,

chat,

plan,

goal

model

string

Optional model. If omitted/empty, server resolves default via user/team/tag policy.

Minimum string length: 1

project_id

string<uuid>

Project ID to scope task to. If omitted, task is user-scoped.

reasoning_effort

enum<string>

Optional reasoning effort override for any model that advertises the value. Read capabilities from /api/v1/models for Neo, byok_models for BYOK, or ai_connection_models for AI connections, according to the user's active model source.

Available options:

none,

minimal,

low,

medium,

high,

xhigh,

max

response_format

enum<string>

Optional response mode.

sse: stream response events
json: immediate acknowledgement with task id/status When omitted, server falls back to Accept header and defaults to sse.

Available options:

sse,

json

sandbox_id

string<uuid>

Optional sandbox to run this task on. Use the id returned by GET /api/v1/sandboxes. When omitted, the Neo-managed cloud sandbox is used. Self-hosted sandboxes require an explicit selection.

schedule

object

Show child attributes

secrets

string[]

Optional secret names to expose at runtime (opt-in). Only listed names are resolved and made available to tools. If omitted or empty, no user/project secrets are exposed.

speed

enum<string>

Optional speed tier for any model that advertises speed support. Read capabilities from /api/v1/models for Neo, byok_models for BYOK, or ai_connection_models for AI connections, according to the user's active model source.

Available options:

standard,

fast

subagent_models

string[]

Optional ordered list of model IDs Neo may use for subagents, exactly as the model source lists them (the main model is always allowed in addition). Use IDs from /api/v1/models. At most 50 entries of at most 200 characters each, from the characters A-Z a-z 0-9 . _ : / @ + -. Each entry is trimmed and compared exactly, and a repeated entry is dropped, keeping its first position. auto is not a subagent model. When set, the list replaces Neo's default subagent models for this request, and the task routes subagents to these models even when model is a specific model. A model the model source cannot use is refused with worker_model_not_admitted.

Maximum array length: 50

Required string length: 1 - 200

subagent_reasoning_effort

enum<string>

default:auto

Optional ceiling for the reasoning effort Neo may pick for a subagent. auto (the default) sets no ceiling; low, medium, high and max cap the effort, and a model that supports less gets its highest supported effort at or below the ceiling.

Available options:

auto,

low,

medium,

high,

max

task

string

Optional shorthand user input. Used only when message.parts is absent.

title

string

Optional task title. When set, the title is persisted on create and auto title generation is skipped. When omitted, the agent generates a title from the first user message.

Required string length: 1 - 500

tool_review

object

Optional per-task pre-execution tool safety review policy. Each tool call is scored against the data-egress, secret-exfiltration and sandbox-destruction policies before it runs. With a reviewer credential configured the default is mode=enforce with fail_closed=false; without one, review is off. This field controls only that reviewer. The separate deterministic protected government-domain policy is admin/plan controlled (see the protected_domains feature flag on PATCH /api/v1/admin/users) and is not settable here; it enforces regardless of this mode.

Show child attributes

triage_ref

object

Optional link to an inbox report (HackerOne, GitHub, or Security Inbox). When set, Neo associates this task with that report so triage status appears in the inbox. Starting triage again for the same report replaces the previous link.

Show child attributes

visibility

enum<string>

Task visibility. Defaults to private when omitted/empty.

Available options:

private,

unlisted,

team

Response

Streaming SSE response

The response is of type string.