My AI API

My AI provides Knowledge (user documents for RAG), Autopilot (scheduled AI tasks), and Chat (conversational AI). All APIs are reached through Prego’s API gateway at /{companyId}/api/my-ai/*.

Who should read this

Using Prego in the browser — Start with Autopilot, Authentication, and Integrations. You usually do not need these HTTP details.
Building integrations — Use this page for paths, payloads, and behavior; pair it with API overview for base URLs and tokens.

Architecture

flowchart LR
  subgraph Client
    A[Prego web app]
  end

  subgraph Gateway
    B[API gateway]
  end

  subgraph Backend
    C[My AI API]
  end

  A -->|Auth, companyId| B
  B -->|Tenant context| C
  C --> B
  B --> A

Knowledge API

Upload and manage documents for RAG (Retrieval-Augmented Generation). Documents are indexed and used as context for chat and Autopilot.

Upload flow

sequenceDiagram
  participant Client
  participant Gateway as API gateway
  participant AI as My AI API

  Client->>Gateway: POST /knowledge/files/init
  Note over Gateway: Resolve companyId, userId
  Gateway->>AI: POST /v1/files/init
  AI-->>Gateway: file_id, upload_url
  Gateway-->>Client: file_id, upload_url

  Client->>AI: PUT upload_url (presigned)
  AI-->>Client: 200 OK

  Client->>Gateway: POST /knowledge/files/complete
  Gateway->>AI: POST /v1/files/complete
  AI->>AI: Indexing (RAG)
  AI-->>Client: 200 OK

Endpoints

Method	Path	Description
GET	`/{companyId}/api/my-ai/knowledge/files`	List user documents
POST	`/{companyId}/api/my-ai/knowledge/files/init`	Init upload — returns `file_id`, `upload_url`
PUT	`{upload_url}`	Upload file binary (presigned URL)
POST	`/{companyId}/api/my-ai/knowledge/files/complete`	Complete upload, trigger indexing
DELETE	`/{companyId}/api/my-ai/knowledge/files/{fileId}`	Delete file and vectors

Example: Init upload

Request

POST /{companyId}/api/my-ai/knowledge/files/init
Content-Type: application/json

{
  "file_name": "policy.pdf",
  "file_size": 102400
}

Response

{
  "file_id": "f_abc123",
  "upload_url": "https://..."
}

Autopilot API

Autopilot pilots run scheduled or manual AI tasks over your Knowledge documents. Configure When (schedule), What (RAG query), How (mode), and Output (webhook).

Execution sequence (generate → save → run → poll)

sequenceDiagram
  participant Client as Prego web app
  participant Gateway as API gateway
  participant AI as My AI API

  Client->>Gateway: POST /autopilot/generate (optional conversation_id, locale)
  Gateway->>AI: POST /v1/autopilot/generate
  AI->>AI: Persist conversation when id sent
  AI-->>Client: AutopilotPlan

  Client->>Gateway: POST /autopilot/pilots
  Gateway->>AI: POST /v1/autopilot/pilots
  AI-->>Client: pilot { id, ... }

  Client->>Gateway: POST /autopilot/pilots/:id/run
  Gateway->>AI: POST /v1/autopilot/pilots/:id/run
  AI->>AI: executePilot (RAG + LLM)
  AI->>AI: Persist run output
  AI-->>Client: { execution_id, output_url, status }

  loop Poll until done
    Client->>Gateway: GET /autopilot/pilots/:id/executions/:runId
    Gateway->>AI: GET /v1/autopilot/.../executions/:runId
    AI-->>Client: execution { steps, output_result, output_url }
  end

  Client->>Gateway: GET .../executions/:runId/output
  Gateway->>AI: GET /v1/autopilot/.../output
  AI->>AI: Load stored output
  AI-->>Client: 200 + markdown body

Client UI: Test run

In the Prego web app, after plan generation (POST .../autopilot/generate), the Autopilot create view can run Test run: it animates plan_steps in the flow UI and refreshes the result preview. That step is preview-only — it does not create a saved pilot or call the live Run now endpoints. User guide: Autopilot.

Execution flow

flowchart TB
  subgraph Triggers
    T1[Run now]
    T2[Cron 9:00 UTC]
  end

  subgraph Schedule
    T1 --> E[Execute]
    T2 --> S{when.config.schedule}
    S -->|manual| Skip[Skip]
    S -->|weekly| Mon{Is Monday?}
    Mon -->|No| Skip
    Mon -->|Yes| E
    S -->|daily| E
  end

  subgraph Execution
    E --> R[RAG: what.config.query or template]
    R --> L[LLM: template prompt]
    L --> M{how.config.mode}
    M -->|draft| Store[Store only]
    M -->|auto| W{webhook_url?}
    W -->|Yes| POST[POST to webhook]
    W -->|No| Store
    POST --> Store
  end

Endpoints

Method	Path	Description
POST	`/{companyId}/api/my-ai/autopilot/generate`	Generate plan from natural language. Body: `natural_language` (required). Optional `conversation_id` or `sessionId` + `locale` — persists user + assistant markdown to the conversation (`thread_kind` autopilot).
GET	`/{companyId}/api/my-ai/autopilot/stats`	KPI: active count, success rate, next run, usefulness
GET	`/{companyId}/api/my-ai/autopilot/pilots`	List pilots (with `last_execution`)
POST	`/{companyId}/api/my-ai/autopilot/pilots`	Create pilot
GET	`/{companyId}/api/my-ai/autopilot/pilots/{id}`	Get pilot
PATCH	`/{companyId}/api/my-ai/autopilot/pilots/{id}`	Update pilot
DELETE	`/{companyId}/api/my-ai/autopilot/pilots/{id}`	Delete pilot
GET	`/{companyId}/api/my-ai/autopilot/pilots/{id}/flow`	Get flow
PUT	`/{companyId}/api/my-ai/autopilot/pilots/{id}/flow`	Update flow
POST	`/{companyId}/api/my-ai/autopilot/pilots/{id}/run`	Run pilot now
GET	`/{companyId}/api/my-ai/autopilot/pilots/{id}/executions`	List executions
GET	`/{companyId}/api/my-ai/autopilot/pilots/{id}/executions/{runId}`	Get execution with steps
GET	`/{companyId}/api/my-ai/autopilot/pilots/{id}/executions/{runId}/output`	Get execution output (stored markdown)
POST	`/{companyId}/api/my-ai/autopilot/pilots/{id}/feedback`	Submit usefulness feedback

Flow format

V4 format (plan_steps, used by UI):

{
  "template_key": "hr",
  "name": "HR weekly report",
  "plan_steps": [
    { "index": 0, "type": "erp_fetch", "label": "Fetch HR data", "description": "...", "badge": "ERP fetch" },
    { "index": 1, "type": "ai_analyze", "label": "Week-over-week analysis", "description": "...", "badge": "AI analyze" }
  ],
  "data_sources": ["hr"],
  "schedule_cron": "0 9 * * 1",
  "schedule_label": "Every Monday 09:00",
  "output_channels": { "slack": true, "email": true, "drive": false, "erp_dashboard": false },
  "mermaid_flow": "flowchart LR ...",
  "preview": { "metrics": [...], "summary": "...", "output_target": "...", "warnings": [] }
}

Legacy format (nodes and output):

{
  "nodes": [
    { "id": "n-when", "type": "when", "label": "When", "config": { "schedule": "weekly" } },
    { "id": "n-what", "type": "what", "label": "What", "config": { "query": "leave requests, approvals" } },
    { "id": "n-how", "type": "how", "label": "How", "config": { "mode": "auto" } },
    { "id": "n-output", "type": "output", "label": "Output" }
  ],
  "output": {
    "webhook_url": "https://example.com/webhook"
  }
}

Node config

Node	Config	Values
`when`	`schedule`	`daily` (9:00 UTC), `weekly` (Mon 9:00 UTC), `manual`
`what`	`query`	Custom RAG query (overrides template default)
`how`	`mode`	`auto` (run + webhook), `draft` (store only), `confirm` (reserved)

Example: Create pilot and update flow

Create pilot

POST /{companyId}/api/my-ai/autopilot/pilots
Content-Type: application/json

{
  "name": "Weekly Report",
  "template_type": "report",
  "enabled": true,
  "flow": { /* AutopilotPlan from generate */ }
}

Update flow

PUT /{companyId}/api/my-ai/autopilot/pilots/{pilotId}/flow
Content-Type: application/json

{
  "flow": {
    "nodes": [
      { "id": "n-when", "type": "when", "label": "When", "config": { "schedule": "weekly" } },
      { "id": "n-what", "type": "what", "label": "What", "config": { "query": "leave requests, approvals" } },
      { "id": "n-how", "type": "how", "label": "How", "config": { "mode": "auto" } },
      { "id": "n-output", "type": "output", "label": "Output" }
    ],
    "output": {
      "webhook_url": "https://example.com/webhook"
    }
  }
}

Generate plan (no save)

POST /{companyId}/api/my-ai/autopilot/generate
Content-Type: application/json

{
  "natural_language": "Send weekly HR attendance summary to Slack"
}

Response (AutopilotPlan): template_key, name, plan_steps, mermaid_flow, preview, output_channels, etc.

Stats

GET /{companyId}/api/my-ai/autopilot/stats

Response: { "activeCount": 5, "successRate": 94, "nextRun": "Mon 09:00", "usefulness": 85 }

Run pilot

POST /{companyId}/api/my-ai/autopilot/pilots/{pilotId}/run

Response

{
  "ok": true,
  "pilot_id": "p_xyz789",
  "execution_id": "e_abc456",
  "status": "done",
  "output": "Generated report content...",
  "output_url": "/api/my-ai/autopilot/pilots/p_xyz789/executions/e_abc456/output",
  "error": null
}

output_url — path to fetch stored output (append to API base + companyId for full URL). Returns 404 if nothing was stored.

Feedback

POST /{companyId}/api/my-ai/autopilot/pilots/{pilotId}/feedback
Content-Type: application/json

{
  "rating": 1,
  "comment": "Optional comment"
}

rating: 1 = useful, 0 = needs improvement.

AutopilotPlan schema

Shared by generate response and flow (create/update pilot).

Field	Type	Description
`template_key`	`"hr" \| "approval" \| "finance" \| "crm" \| "expense" \| "custom"`	Template identifier
`name`	string	Display name
`data_sources`	string[]	e.g. `["hr"]`, `["approval"]`
`pills`	Pill[]	UI badges: `{ title, variant: "data" \| "schedule" \| "output" }`
`schedule_cron`	string	Cron expression (e.g. `"0 9 * * 1"`)
`schedule_label`	string	Human label (e.g. `"Every Monday 09:00"`)
`automation_level`	string	`"draft"`, `"auto"`, etc.
`output_channels`	object	`{ slack, email, drive, erp_dashboard }` (boolean each)
`plan_steps`	PlanStep[]	Execution steps
`mermaid_flow`	string	Mermaid flowchart definition
`preview`	object	`{ metrics, summary, output_target, warnings }`

PlanStep

Field	Type
`index`	number
`type`	`"erp_fetch" \| "ai_analyze" \| "llm_generate" \| "send"`
`label`	string
`description`	string
`badge`	string

Preview.metrics — { key, value, trend: "up" \| "down" \| "neutral" }

Data model (persisted)

Concept	Purpose
Pilots	Saved Autopilot configs: identity, template, schedule, flow JSON, enabled flag
Executions	Run history: status, trigger, short result text, optional `output_url` for long-form markdown
Run steps	Per-step logs for an execution (index, type, status)
Feedback	Optional usefulness ratings tied to a pilot

Webhook integration

When mode is not draft, run completion delivers to configured URLs:

Generic webhook (flow.output.webhook_url):

{
  "pilot_id": "...",
  "pilot_name": "HR weekly report",
  "execution_id": "...",
  "status": "done",
  "triggered_by": "manual",
  "output": "Generated report content...",
  "created_at": "2026-03-19T09:00:00.000Z"
}

On failure: status: "failed", error instead of output.

Slack Incoming Webhook (flow.output.slack_webhook_url): POSTs in Slack format { "text": "..." } for direct Slack posting. URL must be hooks.slack.com.

Email (flow.output.email_to): Sends plain-text email through Prego’s configured provider. email_to can be a string or array of addresses. The From address is set by your environment’s mail configuration.

Use GET .../executions/:runId/output to fetch full markdown body when available.

ERP-backed data (advanced)

Some Autopilot flows can read structured data from your organization’s ERP (for example HR, approvals, finance, or CRM) before the LLM step. Availability and which tables or record types are used depend on your plan and how Prego is connected to your ERP.

Default — Many tenants rely on ERP settings configured once in the admin console (or during onboarding). Integrations should not hard-code production secrets in browsers or public repos.
Flow-level overrides — Server-side automation may supply connection hints inside the pilot flow when your contract allows it. Exact JSON fields evolve with the product; treat the OpenAPI spec and your integration packet as the source of truth, not only this prose.

If you need tenant-wide ERP credentials or record-type overrides, work with your Prego administrator or support — avoid sharing API keys in tickets or chat.

Illustrative `flow` shape (verify in OpenAPI)

The following is a sketch only — property names and allowed data_sources values can change. Confirm against the published spec and your integration packet before shipping.

{
  "flow": {
    "erp": {
      "url": "https://your-erp.example.com",
      "api_key": "<use a server-side secret; never commit or expose in the browser>"
    },
    "data_sources": ["hr", "approval"]
  }
}

Generate (LLM)

POST /generate uses LLM to map natural language to a template. Falls back to keyword matching when LLM fails or returns invalid.

Chat API

See API overview for base URLs and authentication.

Send message

POST /{companyId}/api/my-ai/chat

The My AI service behind the gateway creates the conversation if sessionId is new (client-generated id), updates thread_kind from the first message with an engine value, and stores assistant_variant on assistant messages when the thread is Autopilot.

Field	Required	Description
`message`	Yes	User text (RAG query).
`sessionId`	Yes*	Conversation id (reuse for follow-ups; send a new id for a new thread).
`engine`	No	UI engine label, e.g. `Autopilot` vs `Prego Pro`. Maps to persisted `thread_kind`: `autopilot` vs `chat` (first non-null wins per conversation).
`file_ids`	No	Indexed document ids for RAG scope.
`stream`	No	If `true`, SSE stream of `{ text }` chunks, then `{ done: true, ... }`.
`attachments`	No	Client metadata only today; files use `file_ids` after upload.

*The gateway maps sessionId to an internal conversation id; keep sessionId stable on the client for follow-up messages in the same thread.

Persisted fields

conversations.thread_kind: autopilot | chat | null
messages.assistant_variant: e.g. autopilot on assistant replies in Autopilot threads

Conversations (history)

Method	Path	Description
GET	`/{companyId}/api/my-ai/conversations`	List sessions; responses include `thread_kind` on every item (`null` if unset) so the client can clear stale UI state.
POST	`/{companyId}/api/my-ai/conversations`	Create or ensure a row: body `{ id?, thread_kind? }`. Response includes `thread_kind` (`null` if unset). Optional if you only use `/autopilot/generate` with `conversation_id` (that path creates the row).
GET	`/{companyId}/api/my-ai/conversations/{id}`	Messages include `assistant_variant` when set; response includes `thread_kind` (`null` if unset).
PATCH	`/{companyId}/api/my-ai/conversations/{id}`	Update `title` and/or `thread_kind` (sticky COALESCE same as chat).
DELETE	`/{companyId}/api/my-ai/conversations/{id}`	Delete thread.

Autopilot — In-product guide
API overview — Base URLs and authentication
Glossary — Test run, My AI, API gateway

My AI API

Who should read this

Architecture

Knowledge API

Upload flow

Endpoints

Example: Init upload

Autopilot API

Execution sequence (generate → save → run → poll)

Client UI: Test run

Execution flow

Endpoints

Flow format

Example: Create pilot and update flow

Generate plan (no save)

Stats

Run pilot

Feedback

AutopilotPlan schema

Data model (persisted)

Webhook integration

ERP-backed data (advanced)

Illustrative flow shape (verify in OpenAPI)

Generate (LLM)

Chat API

Send message

Conversations (history)

Related

Illustrative `flow` shape (verify in OpenAPI)