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. |
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. |
: 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."
}'
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
nia search sandbox "Explain the plugin system" \
-r vitejs/vite --ref main
nia search sandbox "How does the router work?" \
-r honojs/hono --no-stream
nia search sandbox job <job-id>
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. |
API reference
Full request/response schemas for these routes live in the API Reference under the Sandbox tag.
