Skip to main content

​
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 must be a full clone URL, for example https://github.com/vercel/ai. Shorthand like vercel/ai is not accepted.

​
When to use what

ApproachBest for
Sandbox search (POST /sandbox/search)One-off questions against a public repo URL; full tree available in the VM; GitLab/Bitbucket as well as GitHub.
Unified search (POST /search)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

MethodPathPurpose
POST/sandbox/searchStart 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)

FieldTypeRequiredDescription
repositorystringYesFull HTTPS URL to a public GitHub, GitLab, or Bitbucket repository.
querystringYesNatural-language question for the agent.
refstringNoBranch, tag, or commit to check out.
streambooleanNoSee 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 — Daytona 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:
typeMeaning
jobIncludes jobId for correlation and polling.
statusJob and runtime status, optional Daytona sandbox id/state.
opencodeRead-only agent stdout/stderr lines or structured stream payloads (stream, line, event).
resultFinal job payload (jobId + serialized job).
errorError message (and optional name / code).
doneStream 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": "https://github.com/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": "https://github.com/vercel/ai",
    "query": "Summarize the core packages in this monorepo."
  }'
Or keep default Accept and set "stream": true in the body.

​
Poll job by id

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

​
Billing

Sandbox search consumes the same query billing operation as unified search. Failed runs are refunded according to server logic.

​
Errors

Common API error codes for this module:
CodeTypical cause
INVALID_SANDBOX_REPOSITORYURL missing, invalid, or host not GitHub/GitLab/Bitbucket.
SANDBOX_PROVISIONING_FAILEDSandbox or workspace setup failed.
SANDBOX_COMMAND_FAILEDAgent command exited with failure.
SANDBOX_QUERY_JOB_NOT_FOUNDUnknown 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.