Skip to Content
APIAPI Reference

API Reference

BiVelio exposes a REST API to integrate your organization with external systems, automate workflows, manage contacts, send communications, and operate AI agents programmatically.

The API supports JWT and API Key authentication. Contact our team for API access.

Authentication

JWT Authentication (available now)

All authenticated BiVelio users can make API requests using their session JWT token. This token is obtained by authenticating via the BiVelio API.

Get a token:

curl -X POST 'https://api.bivelio.com/v1/auth/token?grant_type=password' \
  -H 'apikey: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "your@email.com",
    "password": "your_password"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "v1.MR...",
  "user": {
    "id": "user-uuid",
    "email": "your@email.com"
  }
}

Use the token in requests:

curl -X POST 'https://api.bivelio.com/v1/workflows' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{ "action": "list" }'

The JWT includes the user’s workspace org_id. All returned data is automatically filtered by organization.

JWT tokens expire every 60 minutes. Use the refresh_token to obtain a new access_token without re-authenticating.

API Key Authentication

API Keys allow external developers to integrate their systems without needing an interactive user account. Contact our team for API access.

Header format:

curl -X POST 'https://api.bivelio.com/v1/workflows' \
  -H 'X-API-Key: bv_live_sk_a1b2c3d4e5f6...' \
  -H 'Content-Type: application/json' \
  -d '{ "action": "list" }'

Key types:

PrefixTypeEnvironment
bv_live_sk_Secret KeyProduction
bv_test_sk_Secret KeySandbox
bv_live_pk_Publishable KeyProduction (read-only)

Available scopes:

ScopePermissions
readRead data: list workflows, contacts, messages, invoices
writeCreate and modify data: execute workflows, send messages, create contacts
adminFull management: configure webhooks, manage agents, billing access

API Keys are managed at app.bivelio.com/settings/api where you can create, rotate, and revoke keys, as well as assign granular scopes.

Base URL

Production:

https://api.bivelio.com/v1/

Rate Limiting

Rate limits apply to all API requests based on your plan.

PlanLimitBurst
Starter100 requests/minute20 requests/second
Pro500 requests/minute50 requests/second
EnterpriseUnlimitedCustom

Response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1712505600

When the limit is exceeded, the API returns 429 Too Many Requests:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded the limit of 100 requests per minute.",
    "retry_after": 23
  }
}

Endpoints

All endpoints accept and return JSON. The Content-Type: application/json header is required on all requests with a body.

Workflows

POST /v1/workflows — List workflows

Returns the workflows configured in your organization.

Required scope: read

Request:

{
  "action": "list",
  "data": {
    "status": "active",
    "page": 1,
    "per_page": 20
  }
}

Response:

{
  "success": true,
  "data": {
    "workflows": [
      {
        "id": "wf_a1b2c3d4",
        "name": "Client onboarding",
        "description": "Automated welcome and setup workflow",
        "status": "active",
        "trigger_type": "manual",
        "steps_count": 7,
        "created_at": "2026-03-15T10:30:00Z",
        "updated_at": "2026-04-01T14:22:00Z"
      },
      {
        "id": "wf_e5f6g7h8",
        "name": "Monthly invoicing",
        "description": "Generates and sends invoices on the 1st of each month",
        "status": "active",
        "trigger_type": "cron",
        "steps_count": 4,
        "created_at": "2026-02-20T09:00:00Z",
        "updated_at": "2026-03-28T16:45:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 2,
      "total_pages": 1
    }
  }
}

POST /v1/workflows/execute — Execute a workflow

Launches the execution of a workflow. Returns the instance ID for tracking.

Required scope: write

Request:

{
  "action": "execute",
  "data": {
    "workflow_id": "wf_a1b2c3d4",
    "input": {
      "client_name": "Company ABC",
      "client_email": "contact@companyabc.com",
      "plan": "pro"
    },
    "async": true
  }
}

Response:

{
  "success": true,
  "data": {
    "instance_id": "wfi_x9y8z7w6",
    "workflow_id": "wf_a1b2c3d4",
    "status": "running",
    "started_at": "2026-04-07T12:00:00Z",
    "current_step": 1,
    "total_steps": 7
  }
}

With "async": true, execution runs in the background and you can check the status with /v1/workflows/instances. With "async": false, the response waits for the workflow to finish (60 second timeout).

POST /v1/workflows/instances — List instances

Query the status of workflow executions.

Required scope: read

Request:

{
  "action": "list_instances",
  "data": {
    "workflow_id": "wf_a1b2c3d4",
    "status": "running",
    "page": 1,
    "per_page": 10
  }
}

Response:

{
  "success": true,
  "data": {
    "instances": [
      {
        "instance_id": "wfi_x9y8z7w6",
        "workflow_id": "wf_a1b2c3d4",
        "workflow_name": "Client onboarding",
        "status": "running",
        "current_step": 3,
        "total_steps": 7,
        "input": {
          "client_name": "Company ABC"
        },
        "started_at": "2026-04-07T12:00:00Z",
        "updated_at": "2026-04-07T12:02:30Z"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 10,
      "total": 1,
      "total_pages": 1
    }
  }
}

AI Agents

POST /v1/agents/invoke — Invoke an agent

Executes an AI agent with structured input and receives its response.

Required scope: write

Request:

{
  "action": "invoke",
  "data": {
    "agent_id": "ag_classifier_01",
    "input": {
      "text": "The client wants to upgrade their subscription plan to Enterprise",
      "context": {
        "client_id": "ct_abc123",
        "current_plan": "pro"
      }
    },
    "stream": false
  }
}

Response:

{
  "success": true,
  "data": {
    "execution_id": "age_r4s5t6u7",
    "agent_id": "ag_classifier_01",
    "agent_name": "Intent classifier",
    "output": {
      "intent": "plan_upgrade",
      "confidence": 0.94,
      "suggested_action": "route_to_sales",
      "extracted_entities": {
        "target_plan": "enterprise",
        "client_id": "ct_abc123"
      }
    },
    "tokens_used": 342,
    "credits_consumed": 1,
    "duration_ms": 1850,
    "completed_at": "2026-04-07T12:05:00Z"
  }
}

POST /v1/agents/list — List available agents

Returns the agents configured and active in your organization.

Required scope: read

Request:

{
  "action": "list",
  "data": {
    "status": "active",
    "category": "all"
  }
}

Response:

{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "ag_classifier_01",
        "name": "Intent classifier",
        "description": "Analyzes incoming text and classifies user intent",
        "category": "nlp",
        "status": "active",
        "model": "gemini-2.5-flash",
        "avg_latency_ms": 1200,
        "invocations_today": 47
      },
      {
        "id": "ag_email_draft",
        "name": "Email drafter",
        "description": "Generates draft replies for incoming emails",
        "category": "communication",
        "status": "active",
        "model": "gemini-2.5-flash",
        "avg_latency_ms": 2400,
        "invocations_today": 12
      }
    ]
  }
}

Contacts / CRM

POST /v1/contacts — List or search contacts

Search and filter contacts in your CRM.

Required scope: read

Request:

{
  "action": "list",
  "data": {
    "search": "Company ABC",
    "type": "company",
    "tags": ["client", "active"],
    "page": 1,
    "per_page": 25
  }
}

Response:

{
  "success": true,
  "data": {
    "contacts": [
      {
        "id": "ct_abc123",
        "type": "company",
        "name": "Company ABC S.L.",
        "email": "contact@companyabc.com",
        "phone": "+34 612 345 678",
        "tags": ["client", "active", "pro"],
        "custom_fields": {
          "sector": "technology",
          "tax_id": "B12345678"
        },
        "created_at": "2026-01-10T08:00:00Z",
        "updated_at": "2026-04-05T11:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 25,
      "total": 1,
      "total_pages": 1
    }
  }
}

POST /v1/contacts/create — Create contact

Creates a new contact in the CRM.

Required scope: write

Request:

{
  "action": "create",
  "data": {
    "type": "person",
    "name": "Maria Garcia",
    "email": "maria@example.com",
    "phone": "+34 600 111 222",
    "company_id": "ct_abc123",
    "tags": ["lead", "inbound"],
    "custom_fields": {
      "source": "website",
      "interest": "plan_enterprise"
    }
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "ct_def456",
    "type": "person",
    "name": "Maria Garcia",
    "email": "maria@example.com",
    "phone": "+34 600 111 222",
    "company_id": "ct_abc123",
    "tags": ["lead", "inbound"],
    "custom_fields": {
      "source": "website",
      "interest": "plan_enterprise"
    },
    "created_at": "2026-04-07T12:10:00Z"
  }
}

POST /v1/contacts/update — Update contact

Updates an existing contact. Only included fields are modified.

Required scope: write

Request:

{
  "action": "update",
  "data": {
    "id": "ct_def456",
    "tags": ["client", "active"],
    "custom_fields": {
      "source": "website",
      "interest": "plan_enterprise",
      "converted": true
    }
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "ct_def456",
    "type": "person",
    "name": "Maria Garcia",
    "email": "maria@example.com",
    "tags": ["client", "active"],
    "custom_fields": {
      "source": "website",
      "interest": "plan_enterprise",
      "converted": true
    },
    "updated_at": "2026-04-07T12:15:00Z"
  }
}

Communications

POST /v1/messages/send — Send message

Sends a message via WhatsApp, Telegram, or Email.

Required scope: write

Request:

{
  "action": "send",
  "data": {
    "channel": "whatsapp",
    "to": "+34 612 345 678",
    "message": {
      "type": "text",
      "body": "Hello, your order has been processed successfully. Reference number: #ORD-2026-0451"
    },
    "metadata": {
      "workflow_id": "wf_a1b2c3d4",
      "contact_id": "ct_abc123"
    }
  }
}

Response:

{
  "success": true,
  "data": {
    "message_id": "msg_v1w2x3y4",
    "channel": "whatsapp",
    "to": "+34 612 345 678",
    "status": "sent",
    "sent_at": "2026-04-07T12:20:00Z",
    "whatsapp_message_id": "wamid.HBgLMzQ2MTIzNDU2NzgVAgA..."
  }
}

Supported channels:

Channelchannel valueRequirements
WhatsAppwhatsappVerified number on WhatsApp Business API
TelegramtelegramConnected Telegram Bot
EmailemailConfigured Gmail or SMTP account

POST /v1/messages/list — List conversations

Gets the conversation history with a contact.

Required scope: read

Request:

{
  "action": "list",
  "data": {
    "contact_id": "ct_abc123",
    "channel": "whatsapp",
    "page": 1,
    "per_page": 50
  }
}

Response:

{
  "success": true,
  "data": {
    "messages": [
      {
        "id": "msg_v1w2x3y4",
        "channel": "whatsapp",
        "direction": "outbound",
        "from": "+34 600 000 000",
        "to": "+34 612 345 678",
        "message": {
          "type": "text",
          "body": "Hello, your order has been processed successfully."
        },
        "status": "delivered",
        "sent_at": "2026-04-07T12:20:00Z"
      },
      {
        "id": "msg_a2b3c4d5",
        "channel": "whatsapp",
        "direction": "inbound",
        "from": "+34 612 345 678",
        "to": "+34 600 000 000",
        "message": {
          "type": "text",
          "body": "Perfect, thanks!"
        },
        "status": "received",
        "sent_at": "2026-04-07T12:22:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total": 2,
      "total_pages": 1
    }
  }
}

Documents

POST /v1/documents/extract — OCR extraction

Extracts structured data from a document (invoice, deed, contract, etc.).

Required scope: write

Request:

{
  "action": "extract",
  "data": {
    "document_url": "https://storage.example.com/docs/invoice_2026_001.pdf",
    "document_type": "invoice",
    "language": "en",
    "fields": ["invoice_number", "date", "total", "line_items", "issuer", "recipient"]
  }
}

Response:

{
  "success": true,
  "data": {
    "extraction_id": "ext_m1n2o3p4",
    "document_type": "invoice",
    "confidence": 0.96,
    "extracted": {
      "invoice_number": "INV-2026-001",
      "date": "2026-04-01",
      "total": 1210.00,
      "currency": "EUR",
      "issuer": {
        "name": "Supplier XYZ Ltd.",
        "tax_id": "B98765432"
      },
      "recipient": {
        "name": "Company ABC S.L.",
        "tax_id": "B12345678"
      },
      "line_items": [
        {
          "description": "Consulting services - March 2026",
          "quantity": 1,
          "unit_price": 1000.00,
          "tax_rate": 21,
          "total": 1210.00
        }
      ]
    },
    "credits_consumed": 3,
    "processed_at": "2026-04-07T12:30:00Z"
  }
}

POST /v1/documents/classify — Classify document

Automatically classifies a document by its type and content.

Required scope: write

Request:

{
  "action": "classify",
  "data": {
    "document_url": "https://storage.example.com/docs/unclassified_doc.pdf",
    "categories": ["invoice", "contract", "deed", "receipt", "report", "other"]
  }
}

Response:

{
  "success": true,
  "data": {
    "classification": "contract",
    "confidence": 0.91,
    "subcategory": "service_agreement",
    "summary": "Service agreement contract between two parties for 12 months.",
    "detected_language": "en",
    "page_count": 8,
    "credits_consumed": 2,
    "processed_at": "2026-04-07T12:32:00Z"
  }
}

POST /v1/documents/upload — Upload document

Uploads a document to BiVelio storage and optionally processes it.

Required scope: write

Request:

{
  "action": "upload",
  "data": {
    "filename": "contract_client_abc.pdf",
    "content_base64": "JVBERi0xLjQKMSAwIG9iago8PAov...",
    "folder": "contracts",
    "tags": ["client_abc", "2026"],
    "auto_classify": true,
    "auto_extract": false
  }
}

Response:

{
  "success": true,
  "data": {
    "document_id": "doc_q5r6s7t8",
    "filename": "contract_client_abc.pdf",
    "url": "https://storage.example.com/docs/contracts/contract_client_abc.pdf",
    "size_bytes": 245780,
    "mime_type": "application/pdf",
    "folder": "contracts",
    "tags": ["client_abc", "2026"],
    "classification": {
      "type": "contract",
      "confidence": 0.89
    },
    "uploaded_at": "2026-04-07T12:35:00Z"
  }
}

Calendar

POST /v1/calendar/events — List events

Gets the calendar events for your organization.

Required scope: read

Request:

{
  "action": "list",
  "data": {
    "from": "2026-04-07T00:00:00Z",
    "to": "2026-04-14T23:59:59Z",
    "calendar_id": "primary",
    "include_cancelled": false
  }
}

Response:

{
  "success": true,
  "data": {
    "events": [
      {
        "id": "evt_u8v9w0x1",
        "title": "Meeting with Company ABC",
        "description": "Quarterly project review",
        "start": "2026-04-08T10:00:00Z",
        "end": "2026-04-08T11:00:00Z",
        "location": "Google Meet",
        "attendees": [
          { "email": "contact@companyabc.com", "status": "accepted" },
          { "email": "team@bivelio.com", "status": "accepted" }
        ],
        "source": "google_calendar",
        "google_event_id": "abc123def456"
      }
    ]
  }
}

POST /v1/calendar/create — Create event

Creates a new calendar event.

Required scope: write

Request:

{
  "action": "create",
  "data": {
    "title": "Product demo",
    "description": "New features presentation for Company XYZ",
    "start": "2026-04-10T15:00:00Z",
    "end": "2026-04-10T16:00:00Z",
    "location": "https://meet.google.com/abc-defg-hij",
    "attendees": ["client@xyz.com", "team@bivelio.com"],
    "reminders": [
      { "method": "email", "minutes_before": 60 },
      { "method": "popup", "minutes_before": 15 }
    ],
    "sync_to_google": true
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "evt_y2z3a4b5",
    "title": "Product demo",
    "start": "2026-04-10T15:00:00Z",
    "end": "2026-04-10T16:00:00Z",
    "attendees_notified": true,
    "google_event_id": "xyz789ghi012",
    "created_at": "2026-04-07T12:40:00Z"
  }
}

Billing

POST /v1/invoices/list — List invoices

Gets the invoices issued or received by your organization.

Required scope: read

Request:

{
  "action": "list",
  "data": {
    "type": "issued",
    "status": "pending",
    "from_date": "2026-01-01",
    "to_date": "2026-04-07",
    "page": 1,
    "per_page": 20
  }
}

Response:

{
  "success": true,
  "data": {
    "invoices": [
      {
        "id": "inv_c6d7e8f9",
        "number": "INV-2026-042",
        "type": "issued",
        "status": "pending",
        "client": {
          "id": "ct_abc123",
          "name": "Company ABC S.L."
        },
        "subtotal": 5000.00,
        "tax": 1050.00,
        "total": 6050.00,
        "currency": "EUR",
        "issue_date": "2026-04-01",
        "due_date": "2026-04-30",
        "line_items": [
          {
            "description": "BiVelio Pro License - April 2026",
            "quantity": 10,
            "unit_price": 500.00,
            "tax_rate": 21,
            "total": 6050.00
          }
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 1,
      "total_pages": 1
    }
  }
}

POST /v1/invoices/create — Create invoice

Creates a new invoice in the system.

Required scope: write

Request:

{
  "action": "create",
  "data": {
    "client_id": "ct_abc123",
    "issue_date": "2026-04-07",
    "due_date": "2026-05-07",
    "currency": "EUR",
    "line_items": [
      {
        "description": "Technical consulting - 20 hours",
        "quantity": 20,
        "unit_price": 150.00,
        "tax_rate": 21
      },
      {
        "description": "Monthly software license",
        "quantity": 1,
        "unit_price": 500.00,
        "tax_rate": 21
      }
    ],
    "notes": "Payment due in 30 days. Bank transfer.",
    "auto_send": false
  }
}

Response:

{
  "success": true,
  "data": {
    "id": "inv_g0h1i2j3",
    "number": "INV-2026-043",
    "status": "draft",
    "client": {
      "id": "ct_abc123",
      "name": "Company ABC S.L."
    },
    "subtotal": 3500.00,
    "tax": 735.00,
    "total": 4235.00,
    "currency": "EUR",
    "issue_date": "2026-04-07",
    "due_date": "2026-05-07",
    "pdf_url": "https://storage.example.com/invoices/INV-2026-043.pdf",
    "created_at": "2026-04-07T12:45:00Z"
  }
}

MCP (External Integrations)

POST /v1/mcp/execute — Execute MCP tool

Executes an MCP (Model Context Protocol) action on a connected external provider.

Required scope: write

Request:

{
  "action": "execute",
  "data": {
    "provider": "google_sheets",
    "tool": "read_range",
    "parameters": {
      "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
      "range": "Sheet1!A1:D50"
    }
  }
}

Response:

{
  "success": true,
  "data": {
    "execution_id": "mcp_k4l5m6n7",
    "provider": "google_sheets",
    "tool": "read_range",
    "result": {
      "values": [
        ["Name", "Email", "Plan", "Status"],
        ["Company ABC", "abc@example.com", "pro", "active"],
        ["Company XYZ", "xyz@example.com", "starter", "trial"]
      ],
      "rows_count": 3,
      "columns_count": 4
    },
    "duration_ms": 450,
    "completed_at": "2026-04-07T12:50:00Z"
  }
}

Available MCP providers depend on the integrations configured in your organization. Visit app.bivelio.com/settings/integrations to connect new services.

Webhooks (outbound)

Outbound webhooks allow you to receive real-time notifications when events occur in BiVelio.

POST /v1/webhooks/create — Register webhook

Registers a URL to receive event notifications.

Required scope: admin

Request:

{
  "action": "create",
  "data": {
    "url": "https://your-server.com/api/bivelio-webhook",
    "events": ["workflow.completed", "message.received", "invoice.paid"],
    "secret": "whsec_your_verification_secret",
    "description": "Main integration webhook"
  }
}

Response:

{
  "success": true,
  "data": {
    "webhook_id": "wh_o8p9q0r1",
    "url": "https://your-server.com/api/bivelio-webhook",
    "events": ["workflow.completed", "message.received", "invoice.paid"],
    "status": "active",
    "signing_secret": "whsec_s2t3u4v5w6x7y8z9...",
    "created_at": "2026-04-07T13:00:00Z"
  }
}

POST /v1/webhooks/list — List webhooks

Returns the webhooks registered in your organization.

Required scope: admin

Request:

{
  "action": "list",
  "data": {}
}

Response:

{
  "success": true,
  "data": {
    "webhooks": [
      {
        "webhook_id": "wh_o8p9q0r1",
        "url": "https://your-server.com/api/bivelio-webhook",
        "events": ["workflow.completed", "message.received", "invoice.paid"],
        "status": "active",
        "last_triggered_at": "2026-04-07T12:55:00Z",
        "success_rate": 0.98,
        "created_at": "2026-04-07T13:00:00Z"
      }
    ]
  }
}

Available events:

EventDescription
workflow.completedA workflow has finished execution
workflow.failedA workflow has failed during execution
message.receivedA message has been received (WhatsApp, Telegram, Email)
message.sentA message has been sent successfully
contact.createdA new contact has been created
contact.updatedAn existing contact has been updated
invoice.createdA new invoice has been created
invoice.paidAn invoice has been marked as paid
case.createdA new case/file has been created
case.updatedA case/file has been updated
agent.executedAn AI agent has completed an execution
document.processedA document has been processed (OCR/classification)

Webhook payload format:

{
  "event": "workflow.completed",
  "timestamp": "2026-04-07T13:05:00Z",
  "webhook_id": "wh_o8p9q0r1",
  "data": {
    "instance_id": "wfi_x9y8z7w6",
    "workflow_id": "wf_a1b2c3d4",
    "workflow_name": "Client onboarding",
    "status": "completed",
    "duration_ms": 45000,
    "output": {
      "client_configured": true,
      "welcome_email_sent": true
    }
  }
}

Retry policy:

AttemptDelay
1Immediate
230 seconds
32 minutes
410 minutes
51 hour

After 5 failed attempts, the webhook is automatically deactivated.

Signature verification:

Each webhook request includes an X-BiVelio-Signature header with an HMAC-SHA256 of the body using your signing secret:

const crypto = require('crypto');
 
function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

SDKs

Official SDKs are available for JavaScript/TypeScript and Python. You can also use any HTTP client with the documented endpoints.

JavaScript / TypeScript

npm install @bivelio/sdk
import { BiVelio } from '@bivelio/sdk';
 
const bivelio = new BiVelio({
  apiKey: 'bv_live_sk_a1b2c3d4e5f6...',
});
 
// List workflows
const workflows = await bivelio.workflows.list({ status: 'active' });
 
// Execute a workflow
const instance = await bivelio.workflows.execute('wf_a1b2c3d4', {
  client_name: 'Company ABC',
  plan: 'pro',
});
 
// Send WhatsApp message
const message = await bivelio.messages.send({
  channel: 'whatsapp',
  to: '+34 612 345 678',
  body: 'Your order has been processed.',
});
 
// Invoke AI agent
const result = await bivelio.agents.invoke('ag_classifier_01', {
  text: 'The client wants to change their plan',
});

Python

pip install bivelio
from bivelio import BiVelio
 
client = BiVelio(api_key="bv_live_sk_a1b2c3d4e5f6...")
 
# List contacts
contacts = client.contacts.list(search="Company ABC")
 
# Create invoice
invoice = client.invoices.create(
    client_id="ct_abc123",
    line_items=[
        {
            "description": "Technical consulting",
            "quantity": 20,
            "unit_price": 150.00,
            "tax_rate": 21,
        }
    ],
)
 
# Extract document data
extraction = client.documents.extract(
    document_url="https://storage.example.com/docs/invoice.pdf",
    document_type="invoice",
)

Error Handling

All error responses follow a standard format:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'email' field is required.",
    "details": {
      "field": "email",
      "constraint": "required"
    }
  }
}

HTTP Error Codes

CodeNameDescription
400Bad RequestThe request has an incorrect format or is missing required fields
401UnauthorizedInvalid, expired, or missing token
403ForbiddenThe token does not have permissions for this operation or the resource belongs to another organization
404Not FoundThe requested resource does not exist
409ConflictState conflict (e.g., trying to execute an already running workflow)
422Unprocessable EntityData is syntactically correct but semantically invalid
429Too Many RequestsRequest limit exceeded. Wait for the time indicated in retry_after
500Internal Server ErrorInternal server error. Retry with exponential backoff
503Service UnavailableService temporarily unavailable. Retry in a few minutes

Internal Error Codes

CodeMeaning
AUTH_INVALID_TOKENThe JWT or API Key is not valid
AUTH_EXPIRED_TOKENThe token has expired
AUTH_INSUFFICIENT_SCOPEThe API Key does not have the required scope
VALIDATION_ERRORInput data validation error
RESOURCE_NOT_FOUNDThe requested resource does not exist
RATE_LIMIT_EXCEEDEDRequest limit exceeded
CREDITS_EXHAUSTEDNo AI credits available
WORKFLOW_ALREADY_RUNNINGThe workflow already has a running instance
AGENT_INACTIVEThe agent is not active
INTEGRATION_ERRORExternal integration error (MCP, WhatsApp, etc.)
INTERNAL_ERRORUnexpected internal error

Sandbox Mode

The sandbox environment lets you test the API without affecting real data.

Sandbox mode allows you to test the API without affecting real data:

  • Test API Key: bv_test_sk_xxxxx (generated from the dashboard)
  • Sandbox base URL: https://sandbox.api.bivelio.com/v1/
  • Data created in sandbox is automatically deleted every 24 hours
  • External integrations (WhatsApp, email) are simulated without sending real messages
  • AI credits consumed in sandbox are not deducted from your real balance
# Sandbox request example
curl -X POST 'https://sandbox.api.bivelio.com/v1/messages/send' \
  -H 'X-API-Key: bv_test_sk_a1b2c3d4e5f6...' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "send",
    "data": {
      "channel": "whatsapp",
      "to": "+34 600 000 000",
      "message": {
        "type": "text",
        "body": "Test message from sandbox"
      }
    }
  }'

AI Model

BiVelio uses Google Gemini (Gemini 2.5 Flash) as the primary model for all AI operations. Gemini requests are executed from server-side Edge Functions, never from the frontend.

Each AI operation consumes credits based on complexity:

OperationCredits
Invoke agent (short text)1
Invoke agent (long text / with context)2-5
OCR extraction3
Document classification2
Workflow generation5
Form generation3

Changelog

v1.0.0

Current version of the public API. JWT and API Key endpoints are operational.

Features included in v1.0.0:

  • API Key system with granular scopes
  • Per-plan rate limiting
  • Outbound webhooks with signature verification
  • Official SDKs (JavaScript, Python)
  • Sandbox environment
  • Key management dashboard at app.bivelio.com/settings/api

Need help? Contact our team at support@bivelio.com or through the in-app chat at app.bivelio.com .

SecurityBVOP Program