API Reference

API Documentation

Full programmatic access to your workflows, integrations, and team via REST API.

Base URL│https://api.xavoria.com/v1

Getting Started

The Xavoria API is a REST API that uses standard HTTP verbs, returns JSON, and uses API keys for authentication. All requests must be made over HTTPS.

Protocol

HTTPS only

Format

JSON

Rate limit — Pro

1,000 req / min

Rate limit — Enterprise

Unlimited

Pagination

All list endpoints support cursor-based pagination via query parameters.

http

GET /workflows?page=1&limit=50

Authentication

All API requests require authentication via an API key passed in the Authorization header. Keys are prefixed with xav_.

API Key

http

Authorization: Bearer xav_live_YOUR_API_KEY

OAuth 2.0

OAuth 2.0 is supported for building integrations on top of Xavoria. Contact support@xavoria.com to register your OAuth application.

Getting your API key

Log in to your Xavoria dashboard
Go to Settings → API Keys
Click Create New Key
Copy your key — it won't be shown again

Workflows

Create, configure, and monitor your automation workflows. A workflow consists of one or more triggers and a sequence of actions.

Integrations

Browse available integrations and connect third-party services to use in your workflows.

Team

Manage team members and their access levels. Roles: admin, editor, viewer.

Webhooks

Webhook Events

eventworkflow.completed

Fired when a workflow run finishes successfully.

json

{
  "event": "workflow.completed",
  "workflowId": "wf_01HXYZ",
  "runId": "run_01HABC",
  "status": "success",
  "completedAt": "2025-01-20T14:30:01Z"
}

eventworkflow.failed

Fired when a workflow run fails after all retry attempts.

json

{
  "event": "workflow.failed",
  "workflowId": "wf_01HXYZ",
  "runId": "run_01HABC",
  "error": "Connection timeout to Stripe",
  "failedAt": "2025-01-20T14:30:01Z"
}

Signature Verification

All payloads are signed with HMAC-SHA256. Verify the X-Xavoria-Signature header on every request to ensure authenticity.

Example Requests

List Workflows

bash

curl -X GET https://api.xavoria.com/v1/workflows \
  -H "Authorization: Bearer xav_live_YOUR_API_KEY"

Create a Workflow

bash

curl -X POST https://api.xavoria.com/v1/workflows \
  -H "Authorization: Bearer xav_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice Automation",
    "description": "Auto-create invoices from Stripe",
    "triggers": [{"type": "stripe.payment.completed"}],
    "actions": [{"type": "quickbooks.create_invoice"}]
  }'

Trigger a Workflow Manually

bash

curl -X POST https://api.xavoria.com/v1/workflows/wf_01HXYZ/trigger \
  -H "Authorization: Bearer xav_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": {"customerId": "cus_abc123"}}'

JavaScript / Node.js SDK

javascript

import { XavoriaClient } from '@xavoria/sdk';

const xavoria = new XavoriaClient({ apiKey: process.env.XAVORIA_API_KEY });

// List all active workflows
const { data: workflows } = await xavoria.workflows.list({ status: 'active' });

// Trigger a workflow with custom data
const run = await xavoria.workflows.trigger('wf_01HXYZ', {
  data: { customerId: 'cus_abc123' },
});

// Poll until complete
const result = await xavoria.runs.wait(run.id);
console.log(result.status); // 'success' | 'failed'

Python SDK

python

from xavoria import Client
import os

client = Client(api_key=os.environ["XAVORIA_API_KEY"])

# List all workflows
workflows = client.workflows.list(status="active")

# Trigger and wait for result
run = client.workflows.trigger(
    "wf_01HXYZ",
    data={"customer_id": "cus_abc123"},
)
result = client.runs.wait(run.id)
print(result.status)  # 'success' | 'failed'

Status Codes

Xavoria uses standard HTTP status codes. Errors always include a machine-readable code and a human-readable message.

200

Request succeeded

201

Created

Resource created successfully

400

Bad Request

Invalid request body or missing required fields

401

Unauthorized

Missing or invalid API key

403

Forbidden

Valid key, but insufficient permissions

404

Not Found

Resource does not exist

429

Rate Limited

Too many requests — slow down or upgrade your plan

500

Server Error

Something went wrong on our end

Error Response Format

json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'name' field is required",
    "details": [
      { "field": "name", "message": "Required" }
    ]
  }
}

Ready to build?

Start with a free account — no credit card required.

Start Free Trial Questions?