Provider API Contract

This page documents the complete HTTP API specification that a custom node provider must implement.

Required Endpoints

GET /manifest

Returns the list of available nodes in the provider.

Response:

{
  "nodes": [
    {
      "type": "meu-no-customizado",
      "name": "Meu Nó Customizado",
      "category": "Custom Nodes",
      "timeoutMs": 600000,
      "inputSchema": {
        "campo1": {
          "type": "string",
          "required": true,
          "description": "Descrição do campo"
        },
        "campo2": {
          "type": "number",
          "default": 10,
          "description": "Campo numérico opcional"
        }
      },
      "outputSchema": {
        "resultado": { "type": "string" },
        "timestamp": { "type": "string" }
      }
    }
  ]
}

In the example above, timeoutMs: 600000 sets a 10-minute timeout for this node. If omitted, the default is 30 minutes.

Node Fields

Input Schema

Each field in inputSchema can have:

Output Schema

The outputSchema defines the data the node produces after execution. Each field has:

Outputs are accessible via expressions: {{ steps.meuNo.outputs.resultado }}

POST /execute

Executes a node with the provided data.

Request:

{
  "nodeType": "meu-no-customizado",
  "inputs": {
    "campo1": "valor do campo",
    "campo2": 42
  },
  "runId": "run_abc123",
  "nodeId": "node_xyz789"
}

Response (Success):

{
  "status": "success",
  "logs": [
    "Processando campo1: valor do campo",
    "Resultado calculado com sucesso"
  ],
  "outputs": {
    "resultado": "dados processados",
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "artifacts": []
}

Response (Failure):

{
  "status": "failed",
  "logs": [
    "Processando campo1: valor do campo",
    "ERRO: Campo inválido"
  ],
  "outputs": {},
  "error": {
    "message": "Descrição detalhada do erro"
  },
  "artifacts": []
}

Response Fields

Artifacts

The artifacts field allows the node to return files such as screenshots, PDFs, or other documents. Each artifact can be sent as inline base64:

{
  "artifacts": [
    {
      "type": "screenshot",
      "name": "resultado.png",
      "base64": "iVBORw0KGgoAAAANSUhEUg..."
    },
    {
      "type": "file",
      "name": "relatorio.pdf",
      "base64": "JVBERi0xLjQKJeLj..."
    }
  ]
}

Artifacts are automatically saved to QANode's storage and are available in the execution results.

Optional Endpoint

GET /health

Checks whether the provider is running. Used during the connection test.

Response:

{
  "ok": true,
  "nodeCount": 5
}

Authentication

If the provider requires authentication, configure the Token when registering the provider in QANode. The token will be sent as the Authorization: Bearer {token} header on all requests.

Required Field Validation

QANode validates fields marked as required: true in the inputSchema before calling /execute. If a required field is empty, the execution fails without calling the provider.

Timeouts

The /execute timeout can be customized per node through the timeoutMs field in the manifest. This is useful for nodes that perform long-running operations such as data processing, scraping, or integration with external systems.

{
  "nodes": [
    {
      "type": "processar-lote",
      "name": "Processar Lote",
      "timeoutMs": 1800000,
      "inputSchema": { ... }
    }
  ]
}

In the example above, the node will have a 30-minute timeout (1,800,000ms). If timeoutMs is not defined, the default is 30 minutes (300,000ms).

If the provider does not respond within the timeout, the request is aborted and the node is marked as failed.

Global Flow Timeout

Regardless of each node's individual timeout, QANode enforces a global 24-hour timeout per flow execution. If a flow (or suite) exceeds 24 hours of total execution time, it will be automatically stopped and marked as failed.

Headers Sent by QANode

Content-Type: application/json
Authorization: Bearer {token}  (if configured)

Best Practices

1. Unique type names: Use prefixes to avoid conflicts (e.g., my-company-validator)
2. Descriptive logs: Include logs that help diagnose issues
3. Error handling: Always return status: "failed" with a clear error.message
4. Typed inputs: Define a complete inputSchema so QANode generates appropriate forms
5. Output Schema: Define outputSchema so QANode shows available fields in autocomplete
6. Idempotency: If possible, implement /execute in an idempotent manner
7. Timeout: Use timeoutMs in the manifest for nodes that need more than 30 minutes. Also implement internal timeouts to prevent operations from hanging