Open Harness API

Retrieves all registered harnesses with their current status and capabilities. Use this to discover available harnesses and their supported features before executing operations.

interface ListHarnessesRequest extends PaginationParams {
  status?: HarnessStatus;        // Filter by status
  execution_type?: ExecutionType; // Filter by type
}

interface ListHarnessesResponse extends PaginatedResponse<Harness> {}

Retrieves detailed information about a specific harness including its full capability manifest.

Registers a new harness with the Open Harness system. Typically used by harness vendors or administrators to add support for a new agent harness.

Updates configuration for an existing harness.

Removes a harness from the registry. This does not uninstall the harness itself, only removes it from Open Harness management.

• Cannot unregister a harness with active sessions or running executions
• Credentials associated with this harness will be deleted

Retrieves the full capability manifest for a harness. Use this to determine which operations are supported before attempting them.

Checks connectivity and health of a harness. Returns status information useful for monitoring and debugging.

Validates API credentials for a harness and optionally stores them for future use.

Lists all agents deployed on a specific harness.

Creates and deploys a new agent on the harness. The agent bundle includes the AGENTS.md manifest and any supporting files.

• Agent name in AGENTS.md frontmatter must be unique on this harness
• Maximum bundle size: 50MB
• Files array preserves directory structure via filename paths
• AGENTS.md is required at the root of the bundle

Retrieves the current state and configuration of an agent.

Updates agent configuration without redeploying the full bundle.

Removes an agent from the harness.

• Cannot delete an agent with active sessions
• Associated memory blocks will be deleted

Creates a copy of an existing agent with a new name.

Downloads the complete agent bundle as a ZIP file, including AGENTS.md and all supporting files.

Imports an agent from a previously exported bundle or external source.

Lists all skills installed or registered on the harness.

Registers or installs a skill on the harness. Skills consist of a SKILL.md manifest plus optional supporting files.

• Skill name in SKILL.md frontmatter must match root directory name
• Maximum bundle size: 10MB
• SKILL.md is required at the root
• Binary assets should be in an assets/ subdirectory

Retrieves details about a specific skill.

Uninstalls or unregisters a skill from the harness.

Lists all available versions of a skill.

Reverts a skill to a previous version.

Discovers skills available on the harness that are not yet registered. Useful for finding built-in or auto-detected skills.

Validates a skill bundle without installing it. Returns any errors or warnings.

Downloads the complete skill bundle as a ZIP file.

Upgrades an existing skill to a new version.

Updates skill metadata without uploading a new version.

Executes a task on the harness. Returns immediately with an execution ID; use the stream endpoint to follow progress.

interface ExecuteRequest {
  harnessId: HarnessId;        // path parameter
  message: string;            // 1-100000 chars
  agent_id?: AgentId;         // Use specific agent
  skills?: SkillId[];          // Skills to enable
  model?: string;             // Override default model
  max_tokens?: number;        // 1-200000
  temperature?: number;       // 0.0-1.0
}

Attaches to an existing execution's event stream. Use Last-Event-ID header to resume from a specific point.

Cancels a running execution.

Downloads a specific artifact generated by an execution.

• Content-Type header matches the artifact's MIME type
• Content-Disposition header contains original filename
• Large files use chunked transfer encoding

Creates a new interactive session.

Sends a message to a session with streaming response.

Creates a copy of a session with its history, allowing experimentation from a specific point.

Subscribes to real-time events from the harness.

Registers a webhook endpoint to receive async notifications.

Lists all MCP servers connected to the harness.

Connects a new MCP server to the harness.

interface ConnectMcpServerRequest {
  name: string;           // 1-100 chars
  transport: McpTransport;
  auto_reconnect?: boolean; // default: true
}

type McpTransport =
  | { type: "stdio"; command: string; args?: string[] }
  | { type: "http"; url: string }
  | { type: "sse"; url: string };

Retrieves details about a connected MCP server.

Updates MCP server configuration.

Disconnects an MCP server from the harness.

Lists all tools provided by an MCP server.

Lists all resources provided by an MCP server.

Lists all prompts provided by an MCP server.

Checks the health and connectivity of an MCP server.

Lists all available tools on the harness, including built-in tools, MCP tools, and skill-provided tools.

interface Tool {
  id: string;
  name: string;
  description: string;
  source: "builtin" | "mcp" | "skill" | "custom";
  source_id?: string;        // MCP server ID or skill ID
  input_schema: object;
}

Retrieves the schema and details for a specific tool.

Registers a custom tool with the harness.

interface RegisterToolRequest {
  name: string;            // 1-100 chars
  description: string;     // 1-1000 chars
  input_schema: object;    // JSON Schema
  handler: ToolHandler;
}

type ToolHandler =
  | { type: "webhook"; url: string }
  | { type: "command"; command: string; args?: string[] };

Unregisters a custom tool from the harness.

• Can only unregister custom tools, not built-in or MCP tools

Directly invokes a tool outside of an execution context.

Invokes a tool with streaming output. Useful for tools that produce incremental results.

type ToolStreamEvent =
  | { type: "output"; data: object }
  | { type: "progress"; percentage: number; message: string }
  | { type: "error"; code: string; message: string }
  | { type: "done"; success: boolean; duration_ms: number };

Retrieves the complete memory state for an agent.

interface MemoryState {
  agent_id: AgentId;
  blocks: MemoryBlock[];
  archive_size: number;
}

interface MemoryBlock {
  label: string;
  value: string;
  read_only: boolean;
  updated_at: ISO8601;
}

Lists all memory blocks for an agent.

Retrieves a specific memory block by label.

Creates a new memory block for an agent.

• Label must be unique for this agent
• Labels should be descriptive (e.g., "persona", "user_preferences")

Updates the value of a memory block.

• Cannot update read-only blocks

Deletes a memory block.

• Cannot delete read-only blocks

Searches across memory blocks and archive for relevant content.

interface MemorySearchResult {
  source: "block" | "archive";
  label?: string;          // For block results
  content: string;
  relevance_score: number;  // 0.0-1.0
}

Retrieves the archival/long-term memory for an agent.

Adds an entry to the agent's archival memory.

Exports the complete memory state as a downloadable snapshot.

• ZIP contains blocks.json and archive.json

Imports a previously exported memory snapshot.

• Existing blocks with same labels will be overwritten
• Archive entries are appended, not replaced

Lists all subagents spawned by a parent agent.

interface Subagent {
  id: string;
  name: string;
  description: string;
  status: "idle" | "running" | "completed" | "failed";
  parent_agent_id: AgentId;
  created_at: ISO8601;
}

Spawns a new subagent to handle a specific task in isolation.

Retrieves the current state of a subagent.

Terminates a running subagent.

Delegates a task to a subagent and waits for completion.

Delegates a task to a subagent with streaming progress.

Retrieves the result of a completed subagent task.

Attaches to a running subagent's execution stream.

Lists files in the harness workspace.

Reads the contents of a file.

Writes content to a file, creating it if it doesn't exist.

• Creates parent directories if they don't exist
• Overwrites existing files

Deletes a file or empty directory.

Searches for files using glob patterns or content grep.

Uploads a single file to the workspace.

Uploads multiple files preserving directory structure.

• Maximum total size: 100MB
• Maximum 500 files per batch

Downloads a file with Content-Disposition header for saving.

Downloads multiple files as a ZIP archive.

Creates a directory and any necessary parent directories.

Retrieves the current execution plan (todo list).

interface Plan {
  execution_id: ExecutionId;
  tasks: PlanTask[];
  updated_at: ISO8601;
}

interface PlanTask {
  id: string;
  content: string;
  status: "pending" | "in_progress" | "completed";
  order: number;
}

Updates the execution plan, typically to add or reorder tasks.

Lists all tasks in the execution plan.

Updates a specific task's status or content.

Subscribes to real-time plan updates during execution.

type PlanEvent =
  | { type: "task.added"; task: PlanTask }
  | { type: "task.updated"; task: PlanTask }
  | { type: "task.removed"; task_id: string }
  | { type: "plan.reordered"; task_ids: string[] };

Initiates a conformance test run against a harness.

Streams real-time progress of conformance tests.

type ConformanceEvent =
  | { type: "test.started"; test_id: string; test_name: string }
  | { type: "test.passed"; test_id: string }
  | { type: "test.failed"; test_id: string; error: string }
  | { type: "progress"; completed: number; total: number }
  | { type: "done"; result: ConformanceResult };

Retrieves results from conformance test runs.

Retrieves the current conformance certification status.

interface ConformanceStatus {
  status: "certified" | "partial" | "failing" | "not_tested";
  certified_version?: string;
  pass_rate: number;           // 0.0-1.0
  golden_rule_compliant: boolean;
}

Retrieves diagnostic information about the harness.

interface DiagnosticsResponse {
  harness_id: HarnessId;
  version: string;
  uptime_seconds: number;
  memory_usage_mb: number;
  active_sessions: number;
  active_executions: number;
  connected_mcp_servers: number;
  installed_skills: number;
}

Retrieves recent logs from the harness.

Streams logs in real-time. Useful for debugging and monitoring.