Sandbox search

Overview

Sandbox search provisions an isolated runtime, clones a public Git repository (GitHub, GitLab, or Bitbucket), and runs a read-only agent that answers your question using local files only (no web fetch, no repository edits). When the job finishes, the sandbox is destroyed. Use sandbox search when you want a deep, file-grounded answer against a specific ref without adding the repo as an indexed source. For multi-source or already-indexed content, prefer POST /search instead.

repository can be either a full HTTPS repository URL or owner/repo shorthand. If you use shorthand, the optional provider field defaults to github.

When to use what

Approach	Best for
Sandbox search — API (`POST /sandbox/search`) or CLI (`nia search sandbox`)	One-off questions against a public repo URL or `owner/repo` shorthand; full tree available in the VM; GitLab/Bitbucket as well as GitHub.
Unified search (`POST /search` / `nia search query`)	Indexed sources, multiple repositories, documentation, and hybrid retrieval you already use in Nia.
Tracer (Tracer)	GitHub-centric agent that uses GitHub APIs (no full clone in your account flow).

Authentication

Same as the rest of the API: Authorization: Bearer YOUR_API_KEY. See the API Guide.

Endpoints

Method	Path	Purpose
`POST`	`/sandbox/search`	Start a search job; returns JSON or Server-Sent Events (SSE).
`GET`	`/sandbox/jobs/{jobId}`	Fetch the same job record (status, result, errors). Only the owning user can read a job.

Base URL: https://apigcp.trynia.ai/v2 (see API Guide).

Request body (`POST /sandbox/search`)

Field	Type	Required	Description
`repository`	string	Yes	Full HTTPS URL to a public GitHub, GitLab, or Bitbucket repository, or `owner/repo` shorthand.
`query`	string	Yes	Natural-language question for the agent.
`ref`	string	No	Branch, tag, or commit to check out.
`provider`	string	No	Repository provider for shorthand input: `github`, `gitlab`, or `bitbucket`. Defaults to `github`. Ignored when `repository` is a full URL.
`stream`	boolean	No	See Streaming below.

JSON response

By default the handler returns JSON when the client does not ask for SSE and stream is not true. The payload describes the job, sandbox lifecycle, optional git cache metadata, and (when complete) the execution result:

workspaceKind — e.g. git repository workspace.
job — id, status, query, createdAt, optional startedAt / completedAt.
sandbox — Sandbox identifiers, runtime status, workspace path, preparation and deletion timestamps when applicable.
repository — Present for git workspaces when cache metadata exists (canonical URL, ref, commit SHA, volume hints, etc.).
result — When the job completed successfully: answer, rawOutput, command, exitCode, workspacePath, volumeName, cacheSubpath.
error — When the job failed: message, optional name, code, stack, details, etc.

Statuses evolve from provisioning through running to completed, failed, or cancelled. Poll GET /sandbox/jobs/{jobId} with the job.id from the response if you need updates from another process.

Streaming

The API returns Server-Sent Events when either:

the client sends Accept: text/event-stream, or
the JSON body includes "stream": true.

Send "stream": false" to force a JSON response even if Accept prefers SSE. SSE payloads are JSON objects per event, one per data: line. Event type values include:

`type`	Meaning
`job`	Includes `jobId` for correlation and polling.
`status`	Job and runtime status, optional sandbox id/state.
`opencode`	Read-only agent stdout/stderr lines or structured stream payloads (`stream`, `line`, `event`).
`result`	Final job payload (`jobId` + serialized job).
`error`	Error message (and optional `name` / `code`).
`done`	Stream complete.

The server may emit : keep-alive comment lines every few seconds to keep connections open. Closing the HTTP client cancels the in-flight request; the pipeline treats that as cancellation where supported.

Examples

Search (JSON)

curl -sS -X POST https://apigcp.trynia.ai/v2/sandbox/search \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "vercel/ai",
    "ref": "main",
    "query": "Where is streamText implemented and how does it relate to the data stream protocol?"
  }'

Search (SSE)

curl -N -X POST https://apigcp.trynia.ai/v2/sandbox/search \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "repository": "gitlabhq/gitlabhq",
    "provider": "gitlab",
    "query": "Summarize the core packages in this monorepo."
  }'

Or keep default Accept and set "stream": true in the body. If you send a full URL and provider, the URL takes precedence.

Poll job by id

curl -sS "https://apigcp.trynia.ai/v2/sandbox/jobs/$JOB_ID" \
  -H "Authorization: Bearer $NIA_API_KEY"

CLI usage

The Nia CLI exposes sandbox search as nia search sandbox. It streams progress by default and formats output for interactive terminals.

Flags

Flag	Short	Type	Default	Description
`--repository`	`-r`	string	—	Full HTTPS URL of the git repository (required).
`--ref`	—	string	—	Branch, tag, or commit to check out.
`--stream` / `--no-stream`	—	boolean	`true`	Stream progress updates. Use `--no-stream` for a single JSON response.
`--api-key`	—	string	—	Override the API key for this invocation.
`--verbose`	—	—	—	Show full job metadata and agent protocol events.

Examples

Search a repository (streams by default):

nia search sandbox "Where is streamText implemented?" \
  -r vercel/ai

Search a specific ref:

nia search sandbox "Explain the plugin system" \
  -r vitejs/vite --ref main

Disable streaming for a single JSON response:

nia search sandbox "How does the router work?" \
  -r honojs/hono --no-stream

Re-fetch a previous job:

nia search sandbox job <job-id>

Pipe structured output to jq:

nia search sandbox "List all exported functions" \
  -r sindresorhus/ky | jq .result.answer

On interactive terminals the CLI prints a clean text answer. When piped or redirected, it emits structured JSON — useful for composing with other tools.

Errors

Common API error codes for this module:

Code	Typical cause
`INVALID_SANDBOX_REPOSITORY`	Repository missing, invalid, shorthand malformed, or full URL host not GitHub/GitLab/Bitbucket.
`SANDBOX_PROVISIONING_FAILED`	Sandbox or workspace setup failed.
`SANDBOX_COMMAND_FAILED`	Agent command exited with failure.
`SANDBOX_QUERY_JOB_NOT_FOUND`	Unknown `jobId` or job owned by another user.

See API Guide — Error handling for HTTP status conventions.

API reference

Full request/response schemas for these routes live in the API Reference under the Sandbox tag.

Getting Started

Capabilities

Source Types

Explore

Examples & Guides

Enterprise

Privacy

Overview

When to use what

Authentication

Endpoints

Request body (`POST /sandbox/search`)

JSON response

Streaming

Examples

Search (JSON)

Search (SSE)

Poll job by id

CLI usage

Flags

Examples

Errors

API reference

​Overview

​When to use what

​Authentication

​Endpoints

​Request body (POST /sandbox/search)

​JSON response

​Streaming

​Examples

​Search (JSON)

​Search (SSE)

​Poll job by id

​CLI usage

​Flags

​Examples

​Errors

​API reference

Overview

When to use what

Authentication

Endpoints

Request body (`POST /sandbox/search`)

JSON response

Streaming

Examples

Search (JSON)

Search (SSE)

Poll job by id

CLI usage

Flags

Examples

Errors

API reference