LLM API Guide

This guide is for external LLMs, automation agents, and orchestration systems that need to operate ResearchX through APIs. It focuses on the recommended task flow instead of listing every endpoint.

Use /swagger and /openapi.json for the full API reference.

To configure a loadable skill for an external model or automation agent, use the copyable SKILL.md template in ResearchX API Skill. It is a user documentation template, not a built-in ResearchX global skill.

Capability Model

ResearchX exposes six core concepts for automated data analysis:

Project: the isolation boundary for data, conversations, agents, and files.
Workspace: the local project file area for uploads, scripts, outputs, and reports.
Conversation: the interactive context used by chat-based agents.
Agent Ticket: an asynchronous task with status, events, artifacts, and optional conversation result return.
Container: the project execution environment. Inside containers the project root is always /workspace.
Tool Permission: the confirmation layer for writes, edits, commands, and protected MCP tool calls.

Minimal Analysis Loop

External agents should implement this loop first:

Call the login endpoint and keep the returned token; send later requests with Authorization: Bearer <token>.
Create or select a project.
Upload input data to the project workspace.
Inspect available agents, actions, runtimes, and models.
Create an agent ticket or send a project chat request.
Watch progress through SSE.
Handle permission requests or user questions.
Fetch ticket detail, messages, and artifacts.
Read or download workspace outputs.

POST /api/auth/login
GET /api/projects
POST /api/projects/{projectId}/agent-workspace
GET /api/projects/{projectId}/agents
POST /api/projects/{projectId}/agent-tickets
GET /api/projects/{projectId}/agent-tickets/stream
GET /api/projects/{projectId}/agent-tickets/{ticketId}?mode=full
GET /api/projects/{projectId}/agent-workspace/content?path=reports/summary.md

Agent Ticket Statuses

Handle tickets by status, not by fixed sleeps.

Status	Meaning	Recommended action
`submitted`	Submitted	Continue watching
`validating`	Validating inputs and capabilities	Continue watching
`queued`	Waiting for dispatch	Continue watching
`dispatching`	Dispatching execution	Continue watching
`running`	Running	Continue watching and inspect events when needed
`awaiting_user_input`	Waiting for user input or confirmation	Query question and permission requests
`retry_waiting`	Waiting before retry	Continue watching
`partial_succeeded`	Partially succeeded	Fetch detail and inspect artifacts
`succeeded`	Finished successfully	Fetch outputs
`failed`	Finished with failure	Fetch events and failure messages
`cancelling`	Cancelling	Continue watching
`cancelled`	Cancelled	Stop waiting

Streaming And Polling

Prefer the ticket SSE endpoint:

GET /api/projects/{projectId}/agent-tickets/stream

The stream emits agent_ticket events with ticket_id, status, detail_changed, and conversation_changed. If the stream disconnects, reconnect with the last received event id in the last-event-id header and fetch ticket detail to recover state.

Fallback polling:

GET /api/projects/{projectId}/agent-tickets/{ticketId}?mode=compact
GET /api/projects/{projectId}/agent-tickets/{ticketId}?mode=full

Use compact for refresh and full after completion.

Permission Requests

Protected tool calls may create permission requests:

GET /api/projects/{projectId}/tool-permission-requests?status=pending
GET /api/projects/{projectId}/tool-permission-requests/{requestId}/diff-preview
POST /api/projects/{projectId}/tool-permission-requests/{requestId}/approve
POST /api/projects/{projectId}/tool-permission-requests/{requestId}/deny

Only approve requests that are still pending. Preview file changes before approving write or edit. Review command intent before approving bash. Review server, tool, and arguments before approving mcp.

User Questions

When a task is awaiting_user_input, the agent may be waiting for structured user input:

GET /api/projects/{projectId}/conversation-question-requests?status=pending
POST /api/projects/{projectId}/conversation-question-requests/{requestId}/answer
POST /api/projects/{projectId}/conversation-question-requests/{requestId}/reject

External agents should show these questions to the caller instead of inventing answers without authorization.

Workspace Files

Use workspace-relative paths in API calls, such as data/input.csv or reports/summary.md. In containers the same project is mounted at /workspace.

GET /api/projects/{projectId}/agent-workspace?path=data
GET /api/projects/{projectId}/agent-workspace?query=summary&limit=20
POST /api/projects/{projectId}/agent-workspace
GET /api/projects/{projectId}/agent-workspace/content?path=reports/summary.md
PUT /api/projects/{projectId}/agent-workspace/content
GET /api/projects/{projectId}/agent-workspace/download?path=reports/figures/plot.png

Recommended layout:

Raw inputs in data/.
Scripts in scripts/.
Reports, tables, and plots in reports/ or results/.
Do not write to .agent/.

Error Handling

JSON APIs use a standard envelope:

{
  "ok": false,
  "error": {
    "code": "REQUEST_400_BAD_REQUEST",
    "message": "Human readable error",
    "request_id": "req_xxx"
  }
}

Recommended behavior:

401: refresh login or token.
403: stop retrying and report insufficient access.
404: refresh project, file, or ticket IDs.
409: wait, retry, or use another conversation depending on the conflict.
500: record request_id, inspect events or logs, then decide whether retry is safe.

Current Boundary

The current API is enough for an MVP external automation loop. Some architecture goals, including Temporal engine runs, full resource leases, CWL/DAG orchestration, and DataObjectID-level lineage, are still future-facing. External agents should rely on the currently stable objects: project, workspace, conversation, agent ticket, tool permission, and container.

LLM API Guide

On this page