curl --request POST \
  --url https://api-prod.heliyos.ai/v1/platform/reviews/{id}/decisions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "decision": "approved"
}
'

{
  "meta": {
    "message": "Review approved."
  },
  "data": {
    "status": "APPROVED",
    "applied": {
      "action": "Update",
      "dealId": "6730aa11bb22cc33dd44ee55",
      "schemaId": "66a0f1e2d3c4b5a697880003",
      "object": {
        "_id": "6730aa11bb22cc33dd44ee55",
        "objectType": "deals",
        "data": {
          "deal_name": "Contoso expansion",
          "stage": "Negotiation",
          "amount": 45000
        }
      }
    },
    "orchestrator": {
      "status": "APPROVED",
      "runId": "1a2b3c4d5e6f708192a3b4c5d6e7f809",
      "resuming": true
    },
    "review": {
      "_id": "6731f2c4d5e6f7a8b9c0d1e2",
      "id": "6731f2c4d5e6f7a8b9c0d1e2",
      "type": "deal_update",
      "status": "APPROVED",
      "approval": {
        "status": "APPROVED",
        "by": "66a0f1e2d3c4b5a697881111",
        "at": "2026-11-04T15:12:00.000Z",
        "comment": "Amount agreed on the call.",
        "feedback": null
      },
      "outcome": {
        "ok": true,
        "at": "2026-11-04T15:12:00.000Z",
        "appliedBy": "platform",
        "action": "Update",
        "dealId": "6730aa11bb22cc33dd44ee55"
      }
    }
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

Reviews

Approve or reject a review

Records a person’s decision on a pending review and acts on it. A review is decided once.

Approving carries out the worker’s action:

deal_update and classification_label: Heliyos applies the change before it answers, the same way an edit in Heliyos would, and reports it in applied. If applying fails, nothing is recorded and the review stays pending.
A saved email draft (origin: artifact): the draft is sent before the call answers. If sending fails, the approval is still recorded and orchestrator.error says why.
Every other type: the worker’s run resumes in the background and carries out the action. This happens only once every pending review of that run is decided (orchestrator.pending counts the rest). Read the run, or the review’s outcome, to see the result. If the run is no longer waiting, the decision is recorded and nothing runs.

Rejecting drops the action and tells the worker your feedback. A saved email draft is discarded. As with approval, a paused run resumes, without the action, once every review it waits on is decided.

Changing the proposal before approving. For deal_update, send the fields to write in data (and relationships or schemaId). For other paused actions, send the changed arguments in args. They are checked by the same rules as the worker’s; if they fail, the action does not run and outcome.error says why. data, relationships, schemaId and args are ignored on rejection. A saved email draft is sent as saved: args does not change it.

Already decided. A review that is not pending answers 400 and nothing happens, so sending a decision again after it succeeded does not repeat the action. Send one decision at a time per review: of two decisions sent at the same moment on a deal or label review, one wins and the other answers 409.

Who can decide. Any member of the workspace, and any API key. A decision made with an API key counts as a person’s: it is recorded under the user who created the key and carried out exactly as if that person had approved it in Heliyos. Deciding is blocked while the workspace’s subscription is inactive.

meta.message is Review approved. or Review rejected.. When a deal or label change was applied but the run could not be told yet, it is Review approved; the change is applied, but the agent run could not be notified. and orchestratorError is set: the run picks the decision up later on its own.

POST

platform

reviews

{id}

decisions

curl --request POST \
  --url https://api-prod.heliyos.ai/v1/platform/reviews/{id}/decisions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "decision": "approved"
}
'

{
  "meta": {
    "message": "Review approved."
  },
  "data": {
    "status": "APPROVED",
    "applied": {
      "action": "Update",
      "dealId": "6730aa11bb22cc33dd44ee55",
      "schemaId": "66a0f1e2d3c4b5a697880003",
      "object": {
        "_id": "6730aa11bb22cc33dd44ee55",
        "objectType": "deals",
        "data": {
          "deal_name": "Contoso expansion",
          "stage": "Negotiation",
          "amount": 45000
        }
      }
    },
    "orchestrator": {
      "status": "APPROVED",
      "runId": "1a2b3c4d5e6f708192a3b4c5d6e7f809",
      "resuming": true
    },
    "review": {
      "_id": "6731f2c4d5e6f7a8b9c0d1e2",
      "id": "6731f2c4d5e6f7a8b9c0d1e2",
      "type": "deal_update",
      "status": "APPROVED",
      "approval": {
        "status": "APPROVED",
        "by": "66a0f1e2d3c4b5a697881111",
        "at": "2026-11-04T15:12:00.000Z",
        "comment": "Amount agreed on the call.",
        "feedback": null
      },
      "outcome": {
        "ok": true,
        "at": "2026-11-04T15:12:00.000Z",
        "appliedBy": "platform",
        "action": "Update",
        "dealId": "6730aa11bb22cc33dd44ee55"
      }
    }
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

Approving through the API carries out the worker’s action as if a person clicked Approve in Heliyos: the email is sent, the deal is changed, the meeting is booked. It cannot be undone. Read the review with Get a review first, and approve only what a person has confirmed.

In the Heliyos MCP server: heliyos_reviews_decide.

Authorizations

Authorization

string

header

required

A workspace API key, sent as Authorization: Bearer heliyos_.... Create one in Heliyos under Settings → API keys. A key acts as a workspace admin in the one workspace it was created in.

Path Parameters

string

required

The review's id.

Pattern: ^[0-9a-fA-F]{24}$

Body

application/json

decision

enum<string>

required

approved carries out the action. rejected drops it.

Available options:

approved,

rejected

Example:

"approved"

comment

string | null

A note kept on the review, up to 5,000 characters. Empty or null stores nothing.

Maximum string length: 5000

Example:

"Confirmed with Dana by phone."

feedback

string | null

What to tell the worker, up to 5,000 characters: why you rejected it, what to change, or your answer to a question (kind: question). Empty or null sends nothing.

Maximum string length: 5000

Example:

"Hold the email until legal signs off on the discount."

data

object

deal_update, approving only: the deal's fields to write, as field key to value. Replaces the worker's proposed fields, so include every field you want written. Validated against the deal's object. Omit to write the proposal as it is.

Example:

{ "stage": "Negotiation", "amount": 45000 }

relationships

string[]

deal_update, approving only: ids of the company and people records to link to the deal, up to 500. Omit, or send an empty list, to keep the links the worker proposed.

Maximum array length: 500

A 24-character hexadecimal id.

Pattern: ^[0-9a-fA-F]{24}$

schemaId

string

deal_update creating a deal, approving only: the pipeline (deal object) to create it in. Defaults to the one the worker proposed. Must be a deal object of this workspace.

Pattern: ^[0-9a-fA-F]{24}$

Example:

"66f1a8c3e4b0a1b2c3d4e5f6"

args

object

A paused action, approving only: the arguments you changed, by name, as in proposal.args. They are merged over the worker's arguments, so send only what changes.

Example:

{
  "start": "2026-11-12T15:00:00",
  "timezone": "Europe/London"
}

Response

The decision and the review after it.

Overview

Workspace

Schemas

Records

Timeline

Activities

Interactions

Notes

Tasks

Workers and runs

Reviews

Scouts

Signals

Watchlist

Knowledge base

Files

Labels

Team

Notification settings

Approve or reject a review

Authorizations

Path Parameters

Body

Response