> ## 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. # Create a custom Scout > Creates a custom workspace Scout and starts a preview run of its query. The Scout is created inactive (`isActive: false`) and does not run on any company yet. 1. Create the Scout. `previewStatus` is `running` (or `failed` if the preview could not start; the Scout is still created). 2. Poll Get a workspace Scout (`GET /v1/platform/global-scouts/{id}`) until `previewStatus` is `completed`, and review `previewData`. 3. Send `{"state": "confirmed"}` to Set a workspace Scout's state (`POST /v1/platform/global-scouts/{id}/state`) to activate it, or `{"state": "cancelled"}` to discard it. Once confirmed, the Scout runs on its scope at its cadence, and each run on a company (or on the web) costs credits by `effort`: `low` 2.5, `medium` 7.5, `high` 10. Calling this twice creates two Scouts. > [!NOTE] > > In the Heliyos MCP server: [`heliyos_scouts_create`](https://docs.heliyos.ai/mcp/tools/scouts-and-signals#heliyos-scouts-create). ## OpenAPI ````yaml /api-reference/openapi.json post /v1/platform/global-scouts 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/global-scouts: post: tags: - Scouts summary: Create a custom Scout description: >- Creates a custom workspace Scout and starts a preview run of its query. The Scout is created inactive (`isActive: false`) and does not run on any company yet. 1. Create the Scout. `previewStatus` is `running` (or `failed` if the preview could not start; the Scout is still created). 2. Poll Get a workspace Scout (`GET /v1/platform/global-scouts/{id}`) until `previewStatus` is `completed`, and review `previewData`. 3. Send `{"state": "confirmed"}` to Set a workspace Scout's state (`POST /v1/platform/global-scouts/{id}/state`) to activate it, or `{"state": "cancelled"}` to discard it. Once confirmed, the Scout runs on its scope at its cadence, and each run on a company (or on the web) costs credits by `effort`: `low` 2.5, `medium` 7.5, `high` 10. Calling this twice creates two Scouts. operationId: createGlobalScout parameters: [] requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 200 description: The Scout's name, 1 to 200 characters after trimming. example: Hiring for data roles category: type: string minLength: 1 maxLength: 200 description: >- A short label, 1 to 200 characters after trimming. Signals inherit it. example: Hiring queryTemplate: type: string minLength: 1 maxLength: 5000 description: > What to look for, in plain language, 1 to 5,000 characters after trimming. For the watchlist scopes, write it about "the company": each company's name and website are added when it runs. For `entire_web`, describe the event anywhere on the web. example: >- New job postings at the company for data engineering or analytics roles. cadence: type: string enum: - daily - weekly - monthly description: 'How often it runs: `daily`, `weekly` (default) or `monthly`.' example: weekly applyTo: type: string enum: - watchlist - selected_watchlist - entire_web description: > The scope, fixed once created: `watchlist` (default, every watched company), `selected_watchlist` (only `selectedCompanyIds`) or `entire_web` (one run across the web). example: watchlist effort: type: string enum: - low - medium - high description: >- Search depth: `low`, `medium` (default) or `high`. Higher effort costs more credits per run. example: medium selectedCompanyIds: type: array items: $ref: '#/components/schemas/ObjectId' maxItems: 1000 description: > Required, with at least one id, when `applyTo` is `selected_watchlist`; ignored otherwise. Up to 1,000 company record ids, each a watched company in this workspace. Duplicates are removed. previewCompanyData: type: object properties: company_name: type: string description: The company's name. website: type: string description: The company's website. additionalProperties: false description: > `selected_watchlist` only: the company the preview runs on, as `company_name` (up to 500 characters) and optional `website` (up to 2,000 characters). Ignored for other scopes or when `company_name` is empty. previewLookbackPeriod: type: string enum: - 1_month - 3_months - 6_months description: >- How far back the preview searches: `1_month` (default), `3_months` or `6_months`. example: 1_month outputSchema: type: object properties: {} additionalProperties: true description: > The structured output each run returns. Send `{ "type": "json", "json_schema": { ... } }` or a bare JSON Schema object (`{ "type": "object", "properties": { ... } }`); anything else becomes an empty object schema. In `signals[].items`, `citations`, `confidence_score` and `source` are removed and a `sources` array is added. Omit it for the default schema (see the `ScoutOutputSchema` component). required: - name - category - queryTemplate additionalProperties: false examples: watchlist: summary: Every watched company value: name: Hiring for data roles category: Hiring queryTemplate: >- New job postings at the company for data engineering or analytics roles. cadence: weekly effort: medium selected: summary: Selected watched companies value: name: Expansion into Europe category: Growth & Expansion queryTemplate: >- The company opening an office or entity in a European country. applyTo: selected_watchlist selectedCompanyIds: - 66f1a8c3e4b0a1b2c3d4e5f6 - 66f1a8c3e4b0a1b2c3d4e5f7 previewCompanyData: company_name: Northwind Traders website: https://northwind.example.com previewLookbackPeriod: 3_months responses: '200': description: The new Scout, inactive while its preview runs. 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/GlobalScout' example: meta: message: Custom global scout created successfully data: _id: 6731c0a2b4e5f60718293a4b organizationId: 66a0f1e2d3c4b5a697887766 name: Hiring for data roles type: custom applyTo: watchlist selectedCompanyIds: [] category: Hiring queryTemplate: >- New job postings at the company for data engineering or analytics roles. cadence: weekly effort: medium isActive: false previewStatus: running previewRunId: trun_4b8e2f1a9c7d previewData: null metadata: created: at: '2026-11-04T09:30:00.000Z' by: system updated: at: '2026-11-04T09:30:01.000Z' by: system '400': description: >- VALIDATION_FAILED: a field is invalid, `selectedCompanyIds` is missing for `selected_watchlist`, or a selected company is not a watched company. 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: a `selectedCompanyIds` entry is not a record in this workspace. 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 GlobalScout: type: object description: 'A workspace Scout: what to look for, how often, and on which companies.' properties: _id: $ref: '#/components/schemas/ObjectId' organizationId: allOf: - $ref: '#/components/schemas/ObjectId' description: The workspace the Scout belongs to. name: type: string description: The Scout's name, 1 to 200 characters. type: type: string enum: - default - custom description: > - `default`: a built-in Scout every workspace gets. Six exist: company announcements and press releases, product launches or updates, funding, M&A or financial news, executive changes or quotes, industry analysis mentioning the company, and controversies or negative coverage. They always apply to the watchlist, run daily, and can only be paused or resumed. - `custom`: a Scout you created. Every field except the scope can be changed, and it can be deleted. applyTo: type: string enum: - watchlist - selected_watchlist - entire_web description: > The scope, fixed at creation. - `watchlist`: runs on every watched company, including companies watched later. - `selected_watchlist`: runs only on the companies in `selectedCompanyIds`. - `entire_web`: runs once across the web, not tied to a company. selectedCompanyIds: type: array description: >- The watched companies a `selected_watchlist` Scout runs on. Empty for other scopes. items: $ref: '#/components/schemas/ObjectId' category: type: string description: >- A short label that groups Scouts, for example `Hiring` or `Growth & Expansion`. Signals inherit it. queryTemplate: type: string description: > What the Scout looks for, in plain language, up to 5,000 characters. For the `watchlist` and `selected_watchlist` scopes, the placeholders `{{company_name}}` and `{{company_website}}` are replaced with "the company" and "the company website", and each company's own name and website are added to the query when it runs. cadence: type: string enum: - daily - weekly - monthly description: >- How often it runs. Built-in Scouts run `daily`; custom Scouts default to `weekly`. effort: type: string enum: - low - medium - high description: > Search depth for custom Scouts, `medium` by default. Each run of a custom Scout on one company (or on the web) costs credits by effort: `low` 2.5, `medium` 7.5, `high` 10. May be absent on built-in Scouts. outputSchema: $ref: '#/components/schemas/ScoutOutputSchema' isActive: type: boolean description: > Whether the Scout is running. A new custom Scout is `false` until you confirm its preview. Change it with Set a workspace Scout's state (`POST /v1/platform/global-scouts/{id}/state`). previewStatus: type: string nullable: true enum: - pending - running - completed - failed - null description: > The preview run of a custom Scout. `pending` when created, `running` once the preview started, `completed` when its results are in `previewData`, `failed` if it could not start or finish. Null on built-in Scouts. previewRunId: type: string nullable: true description: The id of the preview run. Null until a preview started. previewData: type: object nullable: true additionalProperties: true description: >- The preview's findings, in the shape of `outputSchema` (by default `signals`, `total_count` and `query_summary`). Null until the preview completed. metadata: $ref: '#/components/schemas/ScoutAuditMetadata' 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: {} ScoutOutputSchema: type: object additionalProperties: true description: > The structured output a custom Scout asks for on each run, as `{ "type": "json", "json_schema": { ... } }` where `json_schema` is a JSON Schema object. The default asks for a `signals` array (each item with `company_name`, `website`, `summary` and `sources`), plus `total_count` and `query_summary`. Built-in Scouts carry their own fixed schema. example: type: json json_schema: type: object properties: signals: type: array items: type: object properties: company_name: type: string website: type: string summary: type: string sources: type: array items: type: string required: - summary total_count: type: number query_summary: type: string required: - signals ScoutAuditMetadata: type: object description: >- When the Scout was created and last changed. `by` is a service label such as `system`, not a user id. properties: created: type: object properties: at: $ref: '#/components/schemas/Timestamp' by: type: string description: Who created it, for example `system`. updated: type: object properties: at: $ref: '#/components/schemas/Timestamp' by: type: string description: Who last changed it, for example `system`. 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.