> ## Documentation Index > Fetch the complete documentation index at: https://docs.neo.projectdiscovery.io/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi/neo.public.openapi.json post /api/v1/tasks openapi: 3.1.0 info: contact: name: ProjectDiscovery url: https://neo.projectdiscovery.io description: Neo API Server - Security agent orchestration platform license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 title: Neo API version: 1.0.0 servers: - description: Production url: https://neo.api.projectdiscovery.io - description: Development url: https://neo.api.dev.projectdiscovery.io - description: Local development url: http://localhost:8080 security: [] tags: - description: Task execution and management name: Tasks - description: Agent listing and management name: Agents - description: Public agent directory name: Agent Directory - description: User file storage management name: Files - description: User working memory management name: Memory - description: Scheduled and recurring task management name: Schedules - description: Knowledge base and semantic search name: Knowledge - description: Encrypted user credentials and API keys name: Secrets - description: Neo API key management for programmatic access name: API Keys - description: User profile and account information name: User - description: Task and LLM usage tracking name: Usage - description: Bring Your Own Key provider management name: BYOK - description: Connect personal AI provider accounts and select them as a model source name: AI Connections - description: Model discovery and capabilities name: Models - description: Third-party integrations name: Integrations - description: Skill knowledge documents for agent prompts name: Skills - description: User-authored tools and toolkit management name: Dynamic Tools - description: Team management and member invitations name: Teams - description: Prompt library management and discovery name: Prompts - description: Slack bot integration for workspace installation and OAuth name: Slack - description: GitHub integration for PR reviews and repository management name: GitHub - description: Vulnerability issue tracking and management name: Issues - description: Subscription billing and plans name: Billing - description: Project management and member assignments name: Projects - description: SSH key pair generation and management for remote server access name: SSH Keys - description: Codebase structural analysis and mapping name: Codemaps - description: AI-generated codebase documentation and security analysis name: CodeWiki - description: Captured HTTP traffic query and replay name: Network Events - description: User and team API activity metadata name: Audit Logs - description: Vulnerability triage for HackerOne, GitHub, and Security Inbox name: Triage paths: /api/v1/tasks: post: tags: - Tasks summary: Create task (stream/json) description: > 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. operationId: post-v1-tasks requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTaskRequest' required: true responses: '200': content: text/event-stream: schema: type: string description: Streaming SSE response '202': content: application/json: schema: $ref: '#/components/schemas/CreateTaskAcceptedResponse' description: Task accepted (JSON acknowledgement mode) '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Bad request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unauthorized '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal server error security: - BearerAuth: [] - ApiKeyAuth: [] components: schemas: CreateTaskRequest: properties: agent_id: description: Bypass AgentSwarm and route to specific agent type: string agent_ids: description: Array of agent IDs for multi-agent orchestration items: type: string type: array ask_question: default: false description: >- 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. type: boolean auto_execute: default: false description: >- When mode=plan, auto-execute the plan without waiting for user approval. Omit for goal mode, which is always automatic. type: boolean browser_session_refs: description: | 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. items: type: string type: array completion_delivery: description: > 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. enum: - webhook - artifact type: string credential_ref: description: | 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:`. 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. type: string credits_budget: default: 500 description: Maximum Neo credits this execution may consume. format: double maximum: 500 minimum: 1 type: number file_keys: description: Optional file references items: type: string type: array id: description: Optional task ID. If omitted or invalid, server generates one. format: uuid type: string isolated: default: false description: Run task in an ephemeral sandbox with no prior user context type: boolean max_duration_seconds: default: 86400 description: >- Maximum cumulative active runtime; approval suspension time is excluded. maximum: 86400 minimum: 300 type: integer max_iterations: description: >- 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. maximum: 5 minimum: 0 type: integer max_steps: description: >- 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). maximum: 200 minimum: 4 type: integer memory_off: default: false description: >- 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. type: boolean message: $ref: '#/components/schemas/MessageInput' mode: default: agent description: >- agent = full tools, chat = limited tools, plan = info-gathering + strategic planning, goal = plan once then autonomously execute and verify until complete enum: - agent - chat - plan - goal type: string model: $ref: '#/components/schemas/ModelType' description: >- Optional model. If omitted/empty, server resolves default via user/team/tag policy. project_id: description: Project ID to scope task to. If omitted, task is user-scoped. format: uuid type: string reasoning_effort: description: > 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. enum: - none - minimal - low - medium - high - xhigh - max type: string response_format: description: > 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. enum: - sse - json type: string sandbox_id: description: | 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. format: uuid type: string schedule: $ref: '#/components/schemas/ScheduleConfigInput' secrets: description: > Optional personal secret names or stable saved-secret references (secret:). Team-shared secrets require an explicit stable reference and current sharing access. Existing personal defaults and project-bound secrets retain their runtime behavior. items: type: string type: array speed: description: | 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. enum: - standard - fast type: string subagent_models: $ref: '#/components/schemas/SubagentModels' subagent_reasoning_effort: $ref: '#/components/schemas/SubagentReasoningEffort' task: description: >- Optional shorthand user input. Used only when message.parts is absent. type: string title: description: | 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. maxLength: 500 minLength: 1 type: string tool_review: description: | 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. properties: fail_closed: description: > When true, a tool call is blocked if the reviewer is unavailable. Defaults to false so a reviewer outage does not halt work. An outage blocks nothing, so set this when a task would rather be held than run unreviewed. type: boolean mode: description: | enforce blocks a violating tool call, shadow records the verdict without blocking, off disables review. enum: - false - shadow - enforce type: string type: object triage_ref: $ref: '#/components/schemas/TriageRef' description: > 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. visibility: description: Task visibility. Defaults to private when omitted/empty. enum: - private - unlisted - team type: string type: object CreateTaskAcceptedResponse: properties: credits_budget: description: Effective per-run Neo credit limit. format: double type: number max_duration_seconds: description: Effective cumulative active-time limit. type: integer status: description: Request acknowledgement status. enum: - accepted type: string task_id: description: Task ID accepted for execution. format: uuid type: string warnings: description: > Non-fatal warnings attached to a successful task acceptance. Only emitted in JSON-mode; SSE callers should poll GET /api/v1/user for the same signal. items: $ref: '#/components/schemas/TaskWarning' type: array required: - task_id - status - credits_budget - max_duration_seconds type: object ErrorResponse: properties: code: description: > Stable machine-readable error code — branch on this rather than matching the human `error`/`message` strings. `access_restricted` (HTTP 403) denies hosted Neo access under the access policy. On team invitations, param=email identifies a restricted recipient rather than the caller; show the error without redirecting the caller. Domain codes include `user_spending_cap_reached`, `project_spending_cap_reached`, and `insufficient_neo_credits`; Free/usage codes include `free_grant_challenge_required`, `free_usage_exhausted`, `free_task_budget_exhausted`, `model_not_available_on_free`, `sandbox_not_available_on_free` (cloud sandbox surfaces are not available on the Free plan; task files remain available from the task), `free_cannot_continue_managed_task` (a task that ran on the standard cloud sandbox cannot be continued on the Free plan; start a new task), `free_origin_not_supported` (integration-originated tasks are not available on the Free plan), `weekly_usage_limit_reached`, `billing_period_usage_limit_reached`, `topup_required`, `subscription_required`, and `isolated_workspace_purged`. Otherwise it mirrors the error kind (e.g. `forbidden`, `invalid_request`, `not_exists`, `already_exists`). example: user_spending_cap_reached type: string error: example: Bad request type: string error_id: description: Correlation id for a specific error instance, when present. type: string kind: description: Coarse error category (e.g. "forbidden request", "invalid request"). example: forbidden request type: string message: description: | Human-readable detail (the kind prefixed to the error). For display, not for branching. type: string param: description: >- Field rejected by the policy; email for a restricted invite recipient. type: string turnstile_site_key: description: | Public Cloudflare Turnstile site key returned only with `free_grant_challenge_required`, so the client can complete the invisible verification before retrying the request. type: string required: - error type: object MessageInput: properties: id: description: Optional message ID. If omitted or invalid, server generates one. format: uuid type: string parts: description: >- Message parts. If absent/empty and task is provided, task is mapped to a text part. items: $ref: '#/components/schemas/MessagePartInputV2' type: array role: description: Optional role. Defaults to user when omitted. enum: - user type: string type: object ModelType: description: | LLM model identifier. Values may be Neo model labels or provider-native model IDs discovered at runtime from an AI connection. "auto" defers model selection to the agent, which picks per-request based on task complexity, cost, and security context. minLength: 1 type: string ScheduleConfigInput: properties: custom_weekdays: description: Weekdays for custom frequency (0=Sunday, 6=Saturday) items: maximum: 6 minimum: 0 type: integer type: array name: description: Human-readable schedule name type: string scan_frequency: enum: - hourly - daily - weekly - monthly - custom type: string schedule_type: enum: - recurring - one_time type: string start_time: description: Start time in HH:MM format (24h) type: string required: - schedule_type type: object SubagentModels: description: | 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`. items: maxLength: 200 minLength: 1 type: string maxItems: 50 type: array SubagentReasoningEffort: default: auto description: | 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. enum: - auto - low - medium - high - max type: string x-enum-varnames: - SubagentReasoningEffortAuto - SubagentReasoningEffortLow - SubagentReasoningEffortMedium - SubagentReasoningEffortHigh - SubagentReasoningEffortMax TriageRef: properties: context: description: > Optional scope for display — HackerOne program handle, GitHub owner/repo, or Security Inbox mailbox email. Empty when unknown. type: string external_id: description: > HackerOne report id, GitHub security advisory id, or Gmail thread id. minLength: 1 type: string source: description: Where the report came from. enum: - hackerone - github - gmail type: string required: - source - external_id type: object TaskWarning: properties: code: enum: - spending_cap_approaching - project_spending_cap_approaching type: string message: type: string required: - code - message type: object MessagePartInputV2: properties: media_type: description: MIME type (for type=file) type: string name: description: File name (for type=file) type: string text: description: Text content (for type=text) type: string type: enum: - text - file type: string url: description: File URL (for type=file) format: uri type: string required: - type type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT authentication token scheme: bearer type: http ApiKeyAuth: description: Neo API key (neo_sk_* prefix) in: header name: X-Api-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.