{
  "components": {
    "schemas": {
      "DecisionUsage": {
        "additionalProperties": false,
        "properties": {
          "input_tokens": {
            "anyOf": [
              {
                "minimum": 0.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Input Tokens"
          },
          "output_tokens": {
            "anyOf": [
              {
                "minimum": 0.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Output Tokens"
          }
        },
        "title": "DecisionUsage",
        "type": "object"
      },
      "ErrorBillingDTO": {
        "additionalProperties": false,
        "properties": {
          "actual_cost_provider": {
            "enum": [
              "openrouter",
              "ai_gateway"
            ],
            "title": "Actual Cost Provider",
            "type": "string"
          },
          "actual_cost_usd": {
            "minimum": 0.0,
            "title": "Actual Cost Usd",
            "type": "number"
          },
          "usage": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/DecisionUsage"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "actual_cost_usd",
          "actual_cost_provider"
        ],
        "title": "ErrorBillingDTO",
        "type": "object"
      },
      "ErrorResponse": {
        "properties": {
          "billing": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ErrorBillingDTO"
              },
              {
                "type": "null"
              }
            ]
          },
          "error_code": {
            "title": "Error Code",
            "type": "string"
          },
          "message": {
            "title": "Message",
            "type": "string"
          }
        },
        "required": [
          "error_code",
          "message"
        ],
        "title": "ErrorResponse",
        "type": "object"
      },
      "JsonObject-Input": {
        "additionalProperties": {
          "$ref": "#/components/schemas/JsonValue-Input"
        },
        "type": "object"
      },
      "JsonObject-Output": {
        "additionalProperties": {
          "$ref": "#/components/schemas/JsonValue-Output"
        },
        "type": "object"
      },
      "JsonValue-Input": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "integer"
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          },
          {
            "items": {
              "$ref": "#/components/schemas/JsonValue-Input"
            },
            "type": "array"
          },
          {
            "additionalProperties": {
              "$ref": "#/components/schemas/JsonValue-Input"
            },
            "type": "object"
          },
          {
            "type": "null"
          }
        ]
      },
      "JsonValue-Output": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "integer"
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          },
          {
            "items": {
              "$ref": "#/components/schemas/JsonValue-Output"
            },
            "type": "array"
          },
          {
            "additionalProperties": {
              "$ref": "#/components/schemas/JsonValue-Output"
            },
            "type": "object"
          },
          {
            "type": "null"
          }
        ]
      },
      "ResearchTaskCitation": {
        "additionalProperties": false,
        "properties": {
          "excerpts": {
            "items": {
              "type": "string"
            },
            "title": "Excerpts",
            "type": "array"
          },
          "title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Title"
          },
          "url": {
            "title": "Url",
            "type": "string"
          }
        },
        "required": [
          "url",
          "title",
          "excerpts"
        ],
        "title": "ResearchTaskCitation",
        "type": "object"
      },
      "ResearchTaskCreateRequest": {
        "additionalProperties": false,
        "properties": {
          "include_raw_tool_calls": {
            "default": false,
            "title": "Include Raw Tool Calls",
            "type": "boolean"
          },
          "input": {
            "minLength": 1,
            "title": "Input",
            "type": "string"
          },
          "output_schema": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/JsonObject-Input"
              },
              {
                "type": "null"
              }
            ],
            "description": "JSON Schema Draft 2020-12 for structured output. `$ref` and `$dynamicRef` values must be local fragments beginning with `#`; external references are rejected. Schemas may contain at most 80,000 compact JSON characters."
          },
          "stream": {
            "default": false,
            "title": "Stream",
            "type": "boolean"
          }
        },
        "required": [
          "input"
        ],
        "title": "ResearchTaskCreateRequest",
        "type": "object"
      },
      "ResearchTaskFailure": {
        "additionalProperties": false,
        "properties": {
          "code": {
            "$ref": "#/components/schemas/ResearchTaskFailureCode"
          },
          "message": {
            "title": "Message",
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "title": "ResearchTaskFailure",
        "type": "object"
      },
      "ResearchTaskFailureCode": {
        "enum": [
          "insufficient_credits",
          "execution_timeout",
          "invalid_output",
          "execution_failed"
        ],
        "title": "ResearchTaskFailureCode",
        "type": "string"
      },
      "ResearchTaskPage": {
        "additionalProperties": false,
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/ResearchTaskSummary"
            },
            "title": "Items",
            "type": "array"
          },
          "next_cursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor"
          }
        },
        "required": [
          "items",
          "next_cursor"
        ],
        "title": "ResearchTaskPage",
        "type": "object"
      },
      "ResearchTaskResponse": {
        "additionalProperties": false,
        "properties": {
          "citations": {
            "anyOf": [
              {
                "items": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/ResearchTaskCitation"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Citations"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "credits_charged": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Credits Charged"
          },
          "error": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ResearchTaskFailure"
              },
              {
                "type": "null"
              }
            ]
          },
          "finished_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Finished At"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "input": {
            "description": "Complete Research Task input.",
            "minLength": 1,
            "title": "Input",
            "type": "string"
          },
          "output": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "$ref": "#/components/schemas/JsonValue-Output"
              },
              {
                "type": "null"
              }
            ],
            "description": "Task output: text, structured JSON, or null. Use status to distinguish a pending result from a completed structured null. Structured responses may contain at most 80,000 compact JSON characters; oversized structured responses cause terminal invalid_output failure.",
            "title": "Output"
          },
          "output_schema": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/JsonObject-Output"
              },
              {
                "type": "null"
              }
            ],
            "description": "Structured output schema requested for this Research Task."
          },
          "status": {
            "$ref": "#/components/schemas/ResearchTaskStatus"
          }
        },
        "required": [
          "id",
          "input",
          "status",
          "created_at",
          "finished_at",
          "output",
          "citations",
          "error",
          "credits_charged"
        ],
        "title": "ResearchTaskResponse",
        "type": "object"
      },
      "ResearchTaskStateEvent": {
        "additionalProperties": false,
        "properties": {
          "task": {
            "$ref": "#/components/schemas/ResearchTaskResponse"
          },
          "task_id": {
            "format": "uuid",
            "title": "Task Id",
            "type": "string"
          },
          "type": {
            "enum": [
              "task.snapshot",
              "task.completed",
              "task.failed"
            ],
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "task_id",
          "task"
        ],
        "title": "ResearchTaskStateEvent",
        "type": "object"
      },
      "ResearchTaskStatus": {
        "enum": [
          "queued",
          "in_progress",
          "completed",
          "failed"
        ],
        "title": "ResearchTaskStatus",
        "type": "string"
      },
      "ResearchTaskSummary": {
        "additionalProperties": false,
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "finished_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Finished At"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "input_preview": {
            "description": "First 500 characters of the Research Task input. Exact reads return the complete input.",
            "maxLength": 500,
            "minLength": 1,
            "title": "Input Preview",
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/ResearchTaskStatus"
          }
        },
        "required": [
          "id",
          "input_preview",
          "status",
          "created_at",
          "finished_at"
        ],
        "title": "ResearchTaskSummary",
        "type": "object"
      },
      "ResearchToolCallEvent": {
        "additionalProperties": false,
        "properties": {
          "call_id": {
            "title": "Call Id",
            "type": "string"
          },
          "finished_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Finished At"
          },
          "outcome": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ToolCallOutcome"
              },
              {
                "type": "null"
              }
            ]
          },
          "raw": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ResearchToolCallRaw"
              },
              {
                "type": "null"
              }
            ]
          },
          "started_at": {
            "format": "date-time",
            "title": "Started At",
            "type": "string"
          },
          "task_id": {
            "format": "uuid",
            "title": "Task Id",
            "type": "string"
          },
          "tool": {
            "enum": [
              "search_web",
              "search_ai",
              "fetch_page",
              "embed_text",
              "decision_query",
              "llm_chat",
              "test_tool",
              "tooling_info"
            ],
            "title": "Tool",
            "type": "string"
          },
          "type": {
            "enum": [
              "tool_call.started",
              "tool_call.completed",
              "tool_call.failed"
            ],
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "task_id",
          "call_id",
          "tool",
          "started_at",
          "finished_at",
          "outcome"
        ],
        "title": "ResearchToolCallEvent",
        "type": "object"
      },
      "ResearchToolCallRaw": {
        "additionalProperties": false,
        "properties": {
          "request": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/JsonValue-Output"
              },
              {
                "type": "null"
              }
            ]
          },
          "response": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/JsonValue-Output"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "request",
          "response"
        ],
        "title": "ResearchToolCallRaw",
        "type": "object"
      },
      "ToolCallOutcome": {
        "description": "High-level outcome for a tool invocation.",
        "enum": [
          "ok",
          "provider_error",
          "budget_exceeded",
          "internal_error",
          "timeout"
        ],
        "title": "ToolCallOutcome",
        "type": "string"
      }
    },
    "securitySchemes": {
      "PlatformApiKey": {
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "title": "Harnyx Research API",
    "version": "0.1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/v1/research/tasks": {
      "get": {
        "operationId": "list_research_tasks_v1_research_tasks_get",
        "parameters": [
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Cursor"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 100,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchTaskPage"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid Research Task cursor."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Platform API-key authentication failed.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer authentication challenge when API-key authentication fails.",
                "example": "Bearer",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Request validation failed (`error_code: validation_failed`)."
          }
        },
        "security": [
          {
            "PlatformApiKey": []
          }
        ],
        "summary": "List Research Tasks"
      },
      "post": {
        "operationId": "create_research_task_v1_research_tasks_post",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Idempotency-Key"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResearchTaskCreateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "text/event-stream": {
                "schema": {
                  "discriminator": {
                    "mapping": {
                      "task.completed": "#/components/schemas/ResearchTaskStateEvent",
                      "task.failed": "#/components/schemas/ResearchTaskStateEvent",
                      "task.snapshot": "#/components/schemas/ResearchTaskStateEvent",
                      "tool_call.completed": "#/components/schemas/ResearchToolCallEvent",
                      "tool_call.failed": "#/components/schemas/ResearchToolCallEvent",
                      "tool_call.started": "#/components/schemas/ResearchToolCallEvent"
                    },
                    "propertyName": "type"
                  },
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ResearchTaskStateEvent"
                    },
                    {
                      "$ref": "#/components/schemas/ResearchToolCallEvent"
                    }
                  ],
                  "title": "Response 200 Create Research Task V1 Research Tasks Post"
                }
              }
            },
            "description": "Current task state, recorded tool-call progress and the settled result as named SSE events."
          },
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchTaskResponse"
                }
              }
            },
            "description": "Research Task accepted.",
            "headers": {
              "Location": {
                "description": "Relative URL for polling the accepted Research Task.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request or Idempotency-Key."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Platform API-key authentication failed.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer authentication challenge when API-key authentication fails.",
                "example": "Bearer",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Idempotency conflict, account task limit, or invalid account status."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Request validation failed (`error_code: validation_failed`)."
          }
        },
        "security": [
          {
            "PlatformApiKey": []
          }
        ],
        "summary": "Create Research Task"
      }
    },
    "/v1/research/tasks/{task_id}": {
      "get": {
        "operationId": "get_research_task_v1_research_tasks__task_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "task_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Task Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "include_raw_tool_calls",
            "required": false,
            "schema": {
              "default": false,
              "title": "Include Raw Tool Calls",
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchTaskResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchTaskResponse",
                  "discriminator": {
                    "mapping": {
                      "task.completed": "#/components/schemas/ResearchTaskStateEvent",
                      "task.failed": "#/components/schemas/ResearchTaskStateEvent",
                      "task.snapshot": "#/components/schemas/ResearchTaskStateEvent",
                      "tool_call.completed": "#/components/schemas/ResearchToolCallEvent",
                      "tool_call.failed": "#/components/schemas/ResearchToolCallEvent",
                      "tool_call.started": "#/components/schemas/ResearchToolCallEvent"
                    },
                    "propertyName": "type"
                  },
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ResearchTaskStateEvent"
                    },
                    {
                      "$ref": "#/components/schemas/ResearchToolCallEvent"
                    }
                  ],
                  "title": "Response 200 Get Research Task V1 Research Tasks  Task Id  Get"
                }
              }
            },
            "description": "Current task state, recorded tool-call progress and the settled result as named SSE events."
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Platform API-key authentication failed.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer authentication challenge when API-key authentication fails.",
                "example": "Bearer",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Research task not found (`error_code: not_found`)."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Request validation failed (`error_code: validation_failed`)."
          }
        },
        "security": [
          {
            "PlatformApiKey": []
          }
        ],
        "summary": "Get Research Task"
      }
    }
  },
  "servers": [
    {
      "url": "https://api.harnyx.ai"
    }
  ]
}