> ## Documentation Index > Fetch the complete documentation index at: https://docs.heliyos.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get a review > Returns one review with everything a person needs to decide it: the worker's proposal (`proposal`, and the type's own fields such as `draftEmail` or `previousVersion` and `newVersion`), its `reasoning`, `confidence` and `approvalReason`, the worker and run it came from (`agentRef`, `runId`), and the records it is about. Unlike List reviews, the records and work the review refers to are resolved: `relatedObjects` holds the company, people and deal records, `interactionData` the email thread or meeting, and `taskData` the task. Once decided, `approval` holds the decision and `outcome` what happened. > [!NOTE] > > In the Heliyos MCP server: [`heliyos_reviews_get`](https://docs.heliyos.ai/mcp/tools/ask-runs-and-reviews#heliyos-reviews-get). ## OpenAPI ````yaml /api-reference/openapi.json get /v1/platform/reviews/{id} openapi: 3.0.3 info: title: Heliyos API version: 1.0.0 description: >- The REST API for Heliyos, the AI operating system for revenue. Every request is scoped to the workspace that owns the API key. Responses are JSON in a `{ meta, data }` envelope; errors use `{ message, error: { code, message, details } }`. contact: name: Heliyos support email: soham@heliyos.ai url: https://www.heliyos.ai servers: - url: https://api-prod.heliyos.ai description: Production security: - bearerAuth: [] tags: - name: Workspace description: >- The workspace your API key belongs to, and the log of credits it has used. Every other call in this API is scoped to this workspace. - name: Schemas description: >- Objects are your record types: companies, people, deal pipelines and any custom objects you add. Each object has fields, and a field's type decides what its records can hold. - name: Records description: >- Records are the rows of an object (base schema): companies, people, deals and custom objects. A record holds field values keyed by the object's field keys and links to other records. - name: Timeline description: >- The AI-written timeline of a company, person or deal: summary entries Heliyos writes on a schedule. For the exact change history see Activities, and for emails and meetings see Interactions. - name: Activities description: >- The change history of records and tasks: who created, changed or deleted what, and when. People, workers and the system each appear as the actor on the changes they make. - name: Interactions description: >- Email threads and meetings synced from connected mailboxes and calendars, linked to the people and companies they involve. - name: Notes description: >- Free-text notes, optionally linked to records, tasks and interactions. Notes show up on the timeline of every record they are linked to, and workers read them as customer memory. - name: Tasks description: >- Work items for people and workers, optionally linked to records. A task can be assigned to people, to workers, or both, and workers can be started on it directly. - name: Workers and runs description: >- Workers are the AI teammates of your workspace (the API calls them agents). Define what each one does and what starts it, ask Heliyos to do work, and follow every run, its steps and the reviews it waits on. - name: Reviews description: >- Reviews keep the team in control of consequential work. When a worker wants to send an email, change a deal, book a meeting, act in a connected app or needs a person's answer, the action waits as a review until someone approves or rejects it. - name: Scouts description: >- Scouts watch companies and the web for events such as funding rounds, product launches, leadership changes or press coverage, and record each finding as a signal. A workspace Scout defines what to look for; company Scouts are its copies running on individual companies. - name: Signals description: >- Signals are what Scouts find: one event, such as a funding round or a new executive, with a summary, its sources and the company it is about. New signals are unread until you mark them read. - name: Watchlist description: >- The watchlist is the set of companies your workers monitor. Each watched company uses one Watcher from your plan: the workers keep it enriched, pull in its emails and meetings, and run Scouts on it. - name: Knowledge base description: >- What your workers know about the business: the business context, four fixed texts (products, pain points, value proposition, qualification criteria) and any custom entries your team adds. Workers read it on their next run. Files your workers read live under Files, with kind `knowledge_base`. - name: Files description: >- Knowledge base files that workers read, and files attached to records, tasks and other resources. The API calls them attachments. Uploading takes three calls: get an upload URL, send the bytes to it, then create the file. - name: Labels description: >- Label groups that sort your email threads, for example Intent or Pricing questions. Heliyos files each classified thread under a group, and each group holds the more specific labels it brings together. The API calls them classification labels. - name: Team description: >- The people in your workspace and their roles: joined members and pending invitations. Inviting someone sends them an email. - name: Notification settings description: >- Which workspace events send notification emails, how often, and to whom. There is one settings document per workspace, shared by everyone in it. paths: /v1/platform/reviews/{id}: get: tags: - Reviews summary: Get a review description: >- Returns one review with everything a person needs to decide it: the worker's proposal (`proposal`, and the type's own fields such as `draftEmail` or `previousVersion` and `newVersion`), its `reasoning`, `confidence` and `approvalReason`, the worker and run it came from (`agentRef`, `runId`), and the records it is about. Unlike List reviews, the records and work the review refers to are resolved: `relatedObjects` holds the company, people and deal records, `interactionData` the email thread or meeting, and `taskData` the task. Once decided, `approval` holds the decision and `outcome` what happened. operationId: getReview parameters: - name: id in: path required: true schema: type: string pattern: ^[0-9a-fA-F]{24}$ description: The review's id. example: 6731f0a9b2c4d5e6f7a8b9c0 responses: '200': description: The review. content: application/json: schema: type: object required: - meta - data properties: meta: type: object required: - message properties: message: type: string description: A human-readable summary of the result. data: $ref: '#/components/schemas/ReviewDetail' example: meta: message: Successful request data: _id: 6731f2c4d5e6f7a8b9c0d1e2 id: 6731f2c4d5e6f7a8b9c0d1e2 organizationId: 66a0f1e2d3c4b5a697887766 type: deal_update kind: action origin: model status: PENDING approval: status: PENDING by: null at: null comment: null feedback: null agent: Pipeline keeper agentRef: id: 6720a0b1c2d3e4f5a6b7c8da name: Pipeline keeper runId: 1a2b3c4d5e6f708192a3b4c5d6e7f809 proposal: title: 'Update deal: Contoso expansion' summary: >- Move the deal to Negotiation and raise the amount to 48,000. args: deal_id: 6730aa11bb22cc33dd44ee55 fields: stage: Negotiation amount: 48000 confidence: 64 reasoning: Procurement confirmed the expanded seat count on the call. approvalReason: The stated confidence is below the workspace's threshold. objectRef: objectId: 6730aa11bb22cc33dd44ee55 objectType: deals objectRefs: - objectId: 6730aa11bb22cc33dd44ee55 objectType: deals name: Contoso expansion dealAction: Update previousVersion: _id: 6730aa11bb22cc33dd44ee55 data: deal_name: Contoso expansion stage: Proposal amount: 36000 relationships: [] newVersion: _id: 6730aa11bb22cc33dd44ee55 data: deal_name: Contoso expansion stage: Negotiation amount: 48000 relationships: [] relatedObjects: - _id: 6730aa11bb22cc33dd44ee55 objectType: deals data: deal_name: Contoso expansion stage: Proposal amount: 36000 previousVersionRelatedObjects: [] newVersionRelatedObjects: [] metadata: created: at: '2026-11-04T14:05:00.000Z' updated: at: '2026-11-04T14:05:00.000Z' '400': description: Validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: 'NOT_FOUND: no review with this id in the workspace.' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: ReviewDetail: description: A review, with the records and work it refers to resolved. allOf: - $ref: '#/components/schemas/Review' - type: object properties: relatedObjects: type: array description: >- The company, people and deal records the review is about: those in `objectRefs` and those linked to the email thread or meeting it sits on. Full records, at most 50. items: type: object additionalProperties: true interactionData: type: object nullable: true additionalProperties: true description: >- The email thread or meeting `objectRef` points at, when it points at one. taskData: type: object nullable: true additionalProperties: true description: >- The task `taskMeta.objectId` (or `objectRef`) points at, when it points at one. previousVersionRelatedObjects: type: array description: '`deal_update`: the records linked to the deal as it is now.' items: type: object additionalProperties: true newVersionRelatedObjects: type: array description: '`deal_update`: the records linked to the deal as proposed.' items: type: object additionalProperties: true ErrorEnvelope: type: object required: - message - error properties: message: type: string description: Same as error.message. error: type: object required: - code - message properties: code: type: string enum: - VALIDATION_FAILED - UNAUTHENTICATED - FORBIDDEN_ACTION - NOT_FOUND - RATE_LIMITED - CONFLICT - INTERNAL message: type: string details: {} Review: type: object description: >- A worker action waiting for, or decided by, a person. Fields beyond the common ones depend on `type`. Reviews raised before a field existed may not carry it. additionalProperties: true properties: _id: $ref: '#/components/schemas/ObjectId' id: type: string description: The review's id, the same value as `_id`. example: 6731f0a9b2c4d5e6f7a8b9c0 organizationId: allOf: - $ref: '#/components/schemas/ObjectId' description: The workspace the review belongs to. type: type: string description: > What is being reviewed. The set is open: actions in connected apps and actions your workspace defines use their own name. Common values: - `email_draft`: an email to send. - `deal_update`: a deal to create (`dealAction: Create`) or change (`dealAction: Update`). - `meeting_scheduled`: a meeting to book or reschedule. - `task`: a task to create or change. - `document`: a file to save on a record or task. - `note`: a note to create. - `object_create`, `object_update`: a record other than a deal to create or change. - `schedule`: a scheduled wake-up for a worker to create or cancel. - `plan`: a plan the worker wants approved before it acts. - `decision`: a question the worker asked (`kind: question`) or an approval it asked for before going on. - `classification_label`: a new label to create. example: email_draft kind: type: string description: | - `action`: a paused action. Approving lets it run. - `plan`: a plan. Approving lets the worker carry it out. - `question`: a question for a person. Answer it in `feedback`. - `approval`: a saved email draft. Approving sends it. example: action origin: type: string description: > - `model`: the worker's run is paused on this action and resumes when it is decided. - `artifact`: the work is already saved (an email draft on its thread) and the decision acts on it. The run does not wait for it. - `autopilot`: the action ran without a person under the workspace's autopilot settings. Kept for the record, already `APPROVED`. example: model status: type: string enum: - PENDING - APPROVED - REJECTED description: >- The decision, mirrored from `approval.status`. Read `approval.status` for the current value. approval: $ref: '#/components/schemas/ReviewApproval' agent: type: string nullable: true description: The name of the worker that raised the review. example: Account researcher agentRef: type: object description: The worker that raised the review. properties: id: type: string nullable: true description: The worker's id. Null when Heliyos itself raised it. name: type: string description: The worker's name. runId: type: string nullable: true description: >- The run that raised the review. Read it with `GET /v1/platform/workers/runs/{id}`. A pending review a later run proposed again points at that later run. example: 0f1e2d3c4b5a69788766554433221100 agentRunId: type: string nullable: true description: The same value as `runId`, under its older name. previousRunId: type: string description: >- The run the review pointed at before a later run proposed the same change again. revisions: type: integer description: >- How many times a later run replaced the proposal while the review was pending. surface: type: string description: >- Where the run that raised it started, for example `chat` or `background`. taskId: type: string nullable: true description: The task the run worked on, when it worked on one. threadId: type: string nullable: true description: The chat conversation the run belongs to, when it started in chat. tool: type: object description: The action the worker wants to take. properties: name: type: string description: >- The action's name, for example `send_email` or `schedule_meeting`. callId: type: string description: Identifies this one call within the run. proposal: type: object description: What the worker proposes. properties: title: type: string description: 'A one-line title, for example `Send email: Renewal terms`.' summary: type: string nullable: true description: The proposal in a sentence or two. args: type: object additionalProperties: true description: >- The action's arguments as the worker proposed them. Send changed values in `args` when you approve. proposedOutput: type: object additionalProperties: true description: The same arguments as `proposal.args`. confidence: type: number nullable: true description: >- How sure the worker said it was, from 0 to 100. Null when it did not say. example: 72 reasoning: type: string description: >- Why the worker proposes the action, in its own words. Empty when it gave no reason. approvalReason: type: string nullable: true description: >- Why the action waits for a person, for example because approval is required for this kind of action or the stated confidence is below the workspace's threshold. objectRef: allOf: - $ref: '#/components/schemas/ReviewObjectRef' description: The first of `objectRefs`. objectRefs: type: array description: The records and tasks the review is about. items: $ref: '#/components/schemas/ReviewObjectRef' dealAction: type: string enum: - Create - Update description: >- `deal_update`: whether the deal is new or an existing one changes. `meeting_scheduled`: `Create` for a new meeting, `Update` for a reschedule. previousVersion: type: object nullable: true additionalProperties: true description: >- `deal_update` with `Update`: the deal as it is now (`_id`, `data`, `relationships`). Null for a new deal. newVersion: type: object nullable: true additionalProperties: true description: >- `deal_update`: the deal as it would be if approved (`data`, `relationships`, and for a new deal the `schemaId` of its pipeline). After an approval with edited fields, the fields as approved. draftEmail: type: object additionalProperties: true description: >- `email_draft`: the email (`subject`, `body`, `from`, `to`, `cc`, `bcc`, `attachments`, and `interactionThreadId`, the email thread it belongs to). Recipients are email addresses or `{ email, name }` objects. draft: type: object additionalProperties: true description: >- `email_draft` with `origin: artifact`: where the saved draft lives (`interactionId` of the email thread, `messageId`). meetingDetails: type: object additionalProperties: true description: >- `meeting_scheduled`: the proposed event (`title`, `startTime`, `endTime`, `timezone`, `participants`, `description`, `location`, `conferencing` and the rest of the event's fields). taskMeta: type: object additionalProperties: true description: >- `task`: the task (`title`, `objectId` of an existing task, `status`, `dueDate`, `description`). documentMeta: type: object additionalProperties: true description: >- `document`: the file (`fileName`, `description`, and when it can be opened, `url`, `mimeType`, `size`, `objectAttachmentId`). noteMeta: type: object additionalProperties: true description: '`note`: the note (`title`, `content`).' categoryName: type: string description: '`classification_label`: the name of the label to create.' categoryDescription: type: string description: '`classification_label`: the label''s description.' outcome: type: object nullable: true additionalProperties: true description: >- What happened after the decision. `ok` (whether it worked), `at`, and `error` when it failed. For an action a run carried out, `result` with what the action returned. For a deal or label Heliyos applied on approval, `appliedBy: platform` with `action`, `dealId` or `labelId`. Absent until something happened. metadata: type: object description: When the review was raised and last changed. properties: created: type: object properties: at: $ref: '#/components/schemas/Timestamp' updated: type: object properties: at: $ref: '#/components/schemas/Timestamp' ObjectId: type: string pattern: ^[0-9a-fA-F]{24}$ description: A 24-character hexadecimal id. example: 66f1a8c3e4b0a1b2c3d4e5f6 ReviewApproval: type: object description: The decision. This is the review's authoritative status. properties: status: type: string enum: - PENDING - PROCESSING - APPROVED - REJECTED description: > - `PENDING`: waiting for a person. - `PROCESSING`: a decision on a `deal_update` or `classification_label` review is being applied right now. It moves to `APPROVED` or `REJECTED` within the same request, or back to `PENDING` if applying failed. - `APPROVED`: approved by a person, or let through by the workspace's autopilot settings (then `by` is `autopilot`). - `REJECTED`: rejected by a person. by: type: string nullable: true description: >- Id of the user who decided. A decision made with an API key is recorded under the user who created the key. `autopilot` when the workspace's autopilot settings approved the action without a person. Null while pending. example: 66a0f1e2d3c4b5a697881111 at: allOf: - $ref: '#/components/schemas/Timestamp' nullable: true description: When it was decided. Null while pending. comment: type: string nullable: true description: The reviewer's note, kept on the review. feedback: type: string nullable: true description: What the reviewer told the worker, for example why it was rejected. editedArgs: type: object additionalProperties: true description: >- The action's arguments as the reviewer changed them on approval, when they changed any. ReviewObjectRef: type: object description: A record or task the review is about. additionalProperties: true properties: objectId: type: string description: Id of the record or task. example: 66f1a8c3e4b0a1b2c3d4e5f6 objectType: type: string nullable: true description: '`company`, `people`, `deals`, a custom object''s type, or `task`.' example: company name: type: string description: The record's display name, when the worker could resolve it. example: Northwind Traders Timestamp: type: string format: date-time description: An ISO 8601 date-time in UTC. example: '2026-11-04T09:30:00.000Z' securitySchemes: bearerAuth: type: http scheme: bearer description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.