API

BiVelio exposes its functionality through Edge Functions deployed on Supabase. All requests require authentication and operate within the context of the user’s workspace.

Authentication

All API requests require a token in the Authorization header:


Authorization: Bearer <token>

Token types

Type	Usage	How to obtain
User JWT	Requests from the frontend or external integrations	Login via Supabase Auth
Service Role Key	Internal calls between Edge Functions	Project environment variable

The user JWT includes the workspace org_id, which is used to filter all data returned by the API.

The Service Role Key has full database access. It must never be exposed in the frontend or shared with third parties.

Base URL


https://<project-ref>.supabase.co/functions/v1/<function-name>

Main endpoints

AI Agents

Endpoint	Method	Description
`agent-structured`	POST	Executes an invocable agent with structured input
`agent-runtime`	POST	Autonomous agent execution runtime
`agent-knowledge-ingest`	POST	Ingests documents into the knowledge base
`agent-test-generator`	POST	Generates tests to validate an agent
`agent-test-runner`	POST	Runs agent validation tests

Communications

Endpoint	Method	Description
`email-classifier`	POST	Classifies an email by category and urgency
`email-draft-generator`	POST	Generates a response draft for an email
`conversation-router`	POST	Routes conversations to the appropriate agent or operator
`telegram-webhook`	POST	Webhook for incoming Telegram messages
`whatsapp-webhook`	POST	Webhook for incoming WhatsApp messages
`whatsapp-send`	POST	Sends a message via the WhatsApp Business API

AI Generation

Endpoint	Method	Description
`ai-generate-spec`	POST	Generates specifications, prompts, or documents with AI
`ai-generate-form`	POST	Generates dynamic forms from a description
`ai-generate-workflow`	POST	Generates BPM workflows from a description
`ai-generate-io-schema`	POST	Generates input/output schemas for agents
`ai-data-classification`	POST	Classifies data according to defined categories
`ai-smart-attachments`	POST	Processes attachments intelligently

Calendar and sync

Endpoint	Method	Description
`calendar-sync`	POST	Syncs Google Calendar events to the system
`calendar-cron`	POST	Runs batch sync for all active connections
`gmail-sync`	POST	Syncs emails from Gmail
`gmail-cron`	POST	Runs Gmail batch sync
`google-oauth`	POST	OAuth flow to connect Google accounts

Workflows and automations

Endpoint	Method	Description
`workflow-engine`	POST	Executes a BPM workflow step by step
`automation-engine`	POST	Evaluates and executes automation rules
`event-dispatcher`	POST	Dispatches system events to subscribed agents

Billing and payments

Endpoint	Method	Description
`create-checkout`	POST	Creates a Stripe checkout session
`stripe-webhook`	POST	Webhook for Stripe events
`credit-engine`	POST	Manages the AI credit ledger
`billing-reminder-ai`	POST	Generates payment reminders with AI
`payment-receipt-ocr`	POST	Extracts data from payment receipts via OCR
`invoice-scheduler`	POST	Schedules automatic invoice generation

Documents and extraction

Endpoint	Method	Description
`deed-extractor`	POST	Extracts structured data from deeds
`docx-tag-extractor`	POST	Extracts tags from DOCX templates
`document-requirement-checker`	POST	Verifies document requirements for a case
`generate-minuta`	POST	Generates minutes from templates

MCP (external integrations)

Endpoint	Method	Description
`mcp-tool-call`	POST	Executes an MCP action on an external provider

Fernando (executive assistant)

Endpoint	Method	Description
`fernando-bridge`	POST	Communication bridge with the Fernando VPS
`fernando-memory`	POST	Memory operations (search, extract, summarize)

Request format

All requests use JSON:


{
  "action": "action_name",
  "data": {
    "field1": "value1",
    "field2": "value2"
  }
}

Response format

Successful responses:


{
  "success": true,
  "data": { ... }
}

Error responses:


{
  "success": false,
  "error": "Error description"
}

AI model

BiVelio uses Google Gemini (Gemini 2.5 Flash) as the primary model for AI operations. Requests to Gemini are made from the Edge Functions, never from the frontend.

Rate limiting

Edge Functions operate within Supabase limits:

Default timeout: 60 seconds (extendable per function)
Concurrency managed automatically by the runtime

Common errors

Code	Meaning
401	Invalid or expired token
403	Insufficient permissions for this operation, or agent inactive
404	Resource not found
422	Invalid input data
429	Request rate limit exceeded
500	Internal server error