> ## 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. # Ask Heliyos > Sends a message to Heliyos, the same as typing it into Ask Heliyos in the app. Heliyos reads the workspace, plans, and calls workers to do the work. It can answer a question ("summarise what changed with Contoso this week") or carry out a job ("draft a follow-up to the Fabrikam thread"). **What it returns.** The call starts a run and answers with `runId`, `status` and `threadId`. With `wait` above 0 it holds the request for up to that many seconds until the run settles: finishes, or stops to wait on a person or a schedule. If the run completes in time, `output` carries the reply. Otherwise follow the run: 1. Call **Get a run** with the `runId` and `wait=30`. Repeat while `status` is `queued` or `running`. 2. When `status` is `completed`, read `output.response`. On `failed`, read `error` with `include=detail`. 3. When `status` is `awaiting_approval`, `paused`, `waiting` or `scheduled`, polling will not move it. A person has to act in Heliyos (Review), or the scheduled time has to come. **List runs** with `threadId` returns every run of a conversation. **Conversations.** Leave `threadId` out to start a new conversation; Heliyos returns its id. Send it back to continue. If the thread's run is still open, your message joins that run instead of starting another: it is queued while the run works, read after the decision while it waits for a review, and resumes it when it is paused. **Reviews.** Consequential actions, such as sending an email or changing a deal, wait for a person's approval unless the workspace's autopilot allows them. The run then shows `awaiting_approval` and lists the reviews in `reviews`. **Credits.** Each call to a custom worker during the run spends credits once the call finishes. Default workers and Heliyos's own reasoning are free. Tools the run uses can spend credits too, for example company enrichment. The run's total is in `usage.credits` on **Get a run**, and each charge is in **List credit usage** under `worker_run`. **Timeouts.** `wait` is at most 90 seconds; set your HTTP client's timeout above it (120 seconds is safe). A run has no fixed time limit and keeps working after the call returns. If you disconnect early, the run is not affected. Every call starts or continues work: calling twice with the same message runs it twice. > [!WARNING] > > Ask Heliyos acts on your workspace. Depending on the request it can create and change records and > tasks, draft and send email, and spend credits. Consequential actions wait for approval in > Heliyos unless your autopilot settings allow them. Calling it twice starts the work twice. > [!NOTE] > > In the Heliyos MCP server: [`heliyos_ask`](https://docs.heliyos.ai/mcp/tools/ask-runs-and-reviews#heliyos-ask). ## OpenAPI ````yaml /api-reference/openapi.json post /v1/platform/orchestrator/chats 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/orchestrator/chats: post: tags: - Workers and runs summary: Ask Heliyos description: >- Sends a message to Heliyos, the same as typing it into Ask Heliyos in the app. Heliyos reads the workspace, plans, and calls workers to do the work. It can answer a question ("summarise what changed with Contoso this week") or carry out a job ("draft a follow-up to the Fabrikam thread"). **What it returns.** The call starts a run and answers with `runId`, `status` and `threadId`. With `wait` above 0 it holds the request for up to that many seconds until the run settles: finishes, or stops to wait on a person or a schedule. If the run completes in time, `output` carries the reply. Otherwise follow the run: 1. Call **Get a run** with the `runId` and `wait=30`. Repeat while `status` is `queued` or `running`. 2. When `status` is `completed`, read `output.response`. On `failed`, read `error` with `include=detail`. 3. When `status` is `awaiting_approval`, `paused`, `waiting` or `scheduled`, polling will not move it. A person has to act in Heliyos (Review), or the scheduled time has to come. **List runs** with `threadId` returns every run of a conversation. **Conversations.** Leave `threadId` out to start a new conversation; Heliyos returns its id. Send it back to continue. If the thread's run is still open, your message joins that run instead of starting another: it is queued while the run works, read after the decision while it waits for a review, and resumes it when it is paused. **Reviews.** Consequential actions, such as sending an email or changing a deal, wait for a person's approval unless the workspace's autopilot allows them. The run then shows `awaiting_approval` and lists the reviews in `reviews`. **Credits.** Each call to a custom worker during the run spends credits once the call finishes. Default workers and Heliyos's own reasoning are free. Tools the run uses can spend credits too, for example company enrichment. The run's total is in `usage.credits` on **Get a run**, and each charge is in **List credit usage** under `worker_run`. **Timeouts.** `wait` is at most 90 seconds; set your HTTP client's timeout above it (120 seconds is safe). A run has no fixed time limit and keeps working after the call returns. If you disconnect early, the run is not affected. Every call starts or continues work: calling twice with the same message runs it twice. operationId: createOrchestratorChat parameters: [] requestBody: required: true content: application/json: schema: type: object properties: message: type: string minLength: 1 maxLength: 20000 description: >- The question or instruction, in plain language. 1 to 20,000 characters after trimming. example: >- Summarise what changed with Contoso this week and list open risks. threadId: type: string pattern: ^[A-Za-z0-9_.:@=+-]+$ minLength: 1 maxLength: 100 description: >- The `threadId` from an earlier answer, to continue that conversation. 1 to 100 characters of letters, digits and `_ . : @ = + -`. Leave it out to start a new conversation. An id Heliyos has not seen starts a new conversation under that id. example: 3fa9c2d17b4e attachments: type: array items: $ref: '#/components/schemas/ObjectId' maxItems: 20 description: >- Ids of files you already uploaded, up to 20. Heliyos and its workers can read them during the run. Each must be a file of this workspace. wait: type: integer minimum: 0 maximum: 90 default: 0 description: >- Seconds to hold the request while the run works, 0 to 90. 0 (the default) answers at once. The call returns as soon as the run finishes or waits on a person or a schedule. example: 60 required: - message additionalProperties: false examples: ask: summary: Ask and wait for the answer value: message: >- Summarise what changed with Contoso this week and list open risks. wait: 60 followUp: summary: Follow up in the same conversation value: message: >- Draft a follow-up email to their champion about the security review. threadId: 3fa9c2d17b4e responses: '200': description: >- The run handling the message, and its reply when it finished within `wait`. 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/AskHeliyosResult' example: meta: message: Successful request data: runId: 9f2c4e7a1b3d4f6a8c0e2b4d6f8a0c1e status: completed threadId: 3fa9c2d17b4e output: final_response_by: Heliyos response: >- Contoso moved to Negotiation on Tuesday. Two risks: procurement wants a security review, and the champion is out until Nov 12. '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: an attachments id is not a file of this workspace. Nothing runs. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: ObjectId: type: string pattern: ^[0-9a-fA-F]{24}$ description: A 24-character hexadecimal id. example: 66f1a8c3e4b0a1b2c3d4e5f6 AskHeliyosResult: type: object properties: runId: type: string nullable: true description: >- The run that handles your message. Follow it with **Get a run**. `null` only when no run could be found for the message (status `not_found`). status: type: string description: > With `wait` 0, what happened to the message: - `queued`: a new run started, or the message was queued on the thread's running run. - `queued_until_decision`: the thread's run waits for a review; your message is read after the decision. - `resuming`: the thread's paused or waiting run resumed with your message. - `already_running`: the thread's run was already working, and your message may not have reached it. Follow the run, then send the message again once it settles. - `not_found`: the thread's run disappeared before the message reached it. Nothing ran; send again. With `wait` above 0, the run's own status when the call returns (see **Get a run** for every value). A run that is still working returns `running` or `queued`. threadId: type: string nullable: true description: >- The conversation. Send it back as `threadId` to continue it. Heliyos makes one up when you send none. output: allOf: - $ref: '#/components/schemas/WorkerRunOutput' description: >- The run's final reply, present when the run produced one within `wait`. 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: {} WorkerRunOutput: type: object additionalProperties: true description: The run's final reply. properties: final_response_by: type: string description: Who wrote the reply, Heliyos or the worker that owned the answer. response: type: string description: The reply text, in Markdown. 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.