Agent API Profile

The full ResearchX API covers administration, conversations, assets, files, containers, and public showcase routes. External LLM agents should not choose from the full surface. This profile defines a compact set of capabilities for data analysis automation.

To hand this profile to an external model as a loadable skill, use the SKILL.md template in ResearchX API Skill. It is a user documentation template for other models and orchestrators, not a built-in platform skill.

Goals

Reduce endpoint choice for models.
Avoid accidental use of admin, showcase, or internal routes.
Give every tool a clear input, output, and recovery strategy.
Provide a stable boundary for a future MCP server, TypeScript SDK, or Python SDK.

Recommended Tool Set

Tool	Endpoint	Purpose
`list_projects`	`GET /api/projects`	Pick an accessible project
`get_project`	`GET /api/projects/{projectId}`	Confirm project state and capabilities
`list_workspace_files`	`GET /api/projects/{projectId}/agent-workspace`	Browse or search data and outputs
`upload_workspace_file`	`POST /api/projects/{projectId}/agent-workspace`	Upload data, scripts, or config
`read_workspace_file`	`GET /api/projects/{projectId}/agent-workspace/content`	Read text outputs
`download_workspace_file`	`GET /api/projects/{projectId}/agent-workspace/download`	Download plots, tables, or binary outputs
`list_analysis_agents`	`GET /api/projects/{projectId}/agents`	Inspect available analysis agents
`create_analysis_task`	`POST /api/projects/{projectId}/agent-tickets`	Create an async analysis task
`watch_task`	`GET /api/projects/{projectId}/agent-tickets/stream`	Watch task status
`get_task_result`	`GET /api/projects/{projectId}/agent-tickets/{ticketId}`	Fetch task detail and artifacts
`list_permission_requests`	`GET /api/projects/{projectId}/tool-permission-requests`	Find pending tool confirmations
`preview_permission_change`	`GET /api/projects/{projectId}/tool-permission-requests/{requestId}/diff-preview`	Review writes or edits
`approve_permission_request`	`POST /api/projects/{projectId}/tool-permission-requests/{requestId}/approve`	Approve execution
`deny_permission_request`	`POST /api/projects/{projectId}/tool-permission-requests/{requestId}/deny`	Deny execution

Do Not Expose By Default

Admin routes.
User deletion, project archive, and bulk destructive routes.
Broad model configuration writes.
Unrestricted MCP server management.
Workspace delete operations unless the caller explicitly grants that capability.

Tool Behavior Rules

Every tool should include projectId, except auth and project listing.
File paths should be workspace-relative, not host absolute paths.
Prefer reports/, results/, scripts/, and data/ for generated files.
Async work returns ticket_id and proceeds to watch_task.
Pending permission requests must be explicitly approved or denied.
Failed tasks must be inspected before retrying.

Suggested MCP Tool Shape

If this profile is wrapped as a ResearchX MCP server, describe tools with narrow schemas:

{
  "name": "create_analysis_task",
  "description": "Create an asynchronous ResearchX analysis task in a project. Use this for long-running data analysis that should produce files in the project workspace.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "projectId": { "type": "string" },
      "title": { "type": "string" },
      "intentSummary": { "type": "string" },
      "files": {
        "type": "array",
        "items": { "type": "string" }
      },
      "expectedOutputs": {
        "type": "array",
        "items": { "type": "string" }
      }
    },
    "required": ["projectId", "title", "intentSummary"]
  }
}

Minimal Scheduler Loop

list_projects
upload_workspace_file
create_analysis_task
watch_task
if pending permission: preview_permission_change -> approve or deny
if awaiting user input: ask caller, then answer through conversation question API
if succeeded: get_task_result -> list_workspace_files -> read/download outputs
if failed: get_task_result -> summarize failure and retry only when safe

Maturity

This profile can start as a documentation contract. It can later become a dedicated MCP server or SDK layer. Implementations should validate endpoint, parameter, and response shape against the OpenAPI registry to avoid drift.

Agent API Profile

On this page