Data Analysis API Cookbook

This page gives practical recipes for external agents. Examples assume a Bearer token and use {projectId} as the project identifier.

Upload A CSV And Start Analysis

Use this when a caller provides a CSV and wants summaries, plots, and conclusions.

Steps:

1. Upload the file to workspace.
2. Inspect available agents.
3. Create an agent ticket.
4. Watch the ticket stream.
5. Read the final report.

Upload:

curl -X POST "$BASE_URL/api/projects/{projectId}/agent-workspace" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@./input.csv" \
  -F "path=data" \
  -F "conflict_policy=overwrite"

path is the destination parent directory. The uploaded filename is taken from the file itself, so this request stores input.csv as data/input.csv.

Create a task:

{
  "task_type": "data_analysis",
  "title": "Analyze uploaded CSV",
  "intent_summary": "Inspect data/input.csv, summarize columns, compute descriptive statistics, and write reports/summary.md.",
  "priority": "normal",
  "conversation_id": "conv_123",
  "add_to_conversation": true,
  "input": {
    "source": "external_api",
    "files": ["data/input.csv"],
    "expected_outputs": ["reports/summary.md", "reports/figures"]
  }
}

task_type should come from an available agent definition returned by GET /api/projects/{projectId}/agents; data_analysis is only an example classification. To target a specific installed agent, include its agent_definition_id in input.

If the task card and result should be returned to a conversation, create or select a conversation first and include both conversation_id and add_to_conversation: true.

Success criteria:

• Ticket status is succeeded or partial_succeeded.
• Full ticket detail contains events and artifacts.
• Workspace contains reports/summary.md or the requested output paths.

Read A Markdown Result

GET /api/projects/{projectId}/agent-workspace/content?path=reports/summary.md

If the path is unknown, search first:

GET /api/projects/{projectId}/agent-workspace?query=summary&limit=20

Download Plots Or Result Files

GET /api/projects/{projectId}/agent-workspace/download?path=reports/figures/plot.png
GET /api/projects/{projectId}/agent-workspace/download?path=results/result.csv

Ask the analysis agent to write stable output paths, for example:

Please save the final report to reports/summary.md and plots to reports/figures/.

Handle Permission Requests

Find pending requests:

GET /api/projects/{projectId}/tool-permission-requests?status=pending

Preview changes:

GET /api/projects/{projectId}/tool-permission-requests/{requestId}/diff-preview

Approve or deny:

POST /api/projects/{projectId}/tool-permission-requests/{requestId}/approve
POST /api/projects/{projectId}/tool-permission-requests/{requestId}/deny

After approval, continue watching the original ticket or conversation stream.

Use A Container Environment

Check container status and options:

GET /api/projects/{projectId}/container/status
GET /api/projects/{projectId}/container/options

Enable and start:

{
  "image": "researchx-runtime:latest",
  "container_cpu_count": 4,
  "container_memory_mb": 8192
}

POST /api/projects/{projectId}/container/enable
POST /api/projects/{projectId}/container/start

Inside the container, write outputs under /workspace/reports or /workspace/results.

Diagnose Failed Tasks

When a ticket fails:

1. Fetch GET /api/projects/{projectId}/agent-tickets/{ticketId}?mode=full.
2. Inspect latest_run.failure_code and latest_run.failure_message.
3. Inspect error-level events.
4. Check whether artifacts contain partial outputs.
5. If containers were involved, inspect container events or build logs.

Retry only when the failure is input, environment, permission, or transient service related.

Add MCP Tools

GET /api/projects/{projectId}/mcp/servers
POST /api/projects/{projectId}/mcp/servers
POST /api/projects/{projectId}/mcp/servers/{serverId}/test
GET /api/projects/{projectId}/mcp/servers/{serverId}/tools

Recommended setup:

• Expose only tools needed for the task.
• Require confirmation for tools that write to external systems.
• Keep allowed_tools and confirmation_tools explicit.

Use Chat For Lightweight Analysis

Use project chat for shorter tasks:

POST /api/projects/{projectId}/chat

Consume the SSE stream and wait for done before reading conversation messages or workspace outputs. Prefer agent tickets for long-running work, cancellation, artifacts, and reliable status tracking.