Craveva AI

API Master Documentation

Complete API reference for technology partners and external developers. Build AI agents, integrate data sources, deploy to platforms, and manage everything programmatically.

Base URL: https://ai.craveva.com/api/v1 or /api/v1 (relative)

All API requests should be made to this base URL with the appropriate endpoint path. Most endpoints require authentication via API key or JWT token in the Authorization header.

API Test Console Available

Log in to test API endpoints directly from this page.

Authentication

Most endpoints require authentication using an API key or JWT token. Include your credentials in the Authorization header:Authorization: Bearer YOUR_API_KEY_OR_TOKEN

Authentication Endpoints

POST/api/v1/auth/register

Register User

Create a new user account in the system.

Request Body Example:

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "full_name": "John Doe",
  "company_name": "Example Corp"
}

Response Example:

{
  "user": {
    "id": "user_id",
    "email": "user@example.com",
    "full_name": "John Doe",
    "is_verified": false
  },
  "token": "jwt_token_here",
  "refresh_token": "refresh_token_here"
}
POST/api/v1/auth/login

Login

Authenticate user and receive access tokens.

Request Body Example:

{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}

Response Example:

{
  "user": {
    "id": "user_id",
    "email": "user@example.com",
    "role": "admin",
    "company_id": "company_id"
  },
  "token": "jwt_token_here",
  "refresh_token": "refresh_token_here"
}
GET/api/v1/auth/me

Get Current User

Retrieve information about the currently authenticated user.

Response Example:

{
  "user": {
    "id": "user_id",
    "email": "user@example.com",
    "full_name": "John Doe",
    "role": "admin",
    "company_id": "company_id"
  }
}
POST/api/v1/auth/refresh

Refresh Token

Generate a new access token using a refresh token.

Request Body Example:

{
  "refresh_token": "refresh_token_here"
}

Response Example:

{
  "token": "new_jwt_token_here",
  "refresh_token": "new_refresh_token_here"
}
POST/api/v1/auth/logout

Logout

Log out the current user and invalidate refresh token.

Request Body Example:

{
  "refresh_token": "refresh_token_here"
}

Response Example:

{
  "success": true,
  "message": "Logged out successfully"
}
POST/api/v1/auth/password/forgot

Forgot Password

Request a password reset email.

Request Body Example:

{
  "email": "user@example.com"
}

Response Example:

{
  "success": true,
  "message": "Password reset email sent"
}
POST/api/v1/auth/password/reset

Reset Password

Reset password using a reset token.

Request Body Example:

{
  "token": "reset_token_here",
  "password": "NewSecurePassword123!"
}

Response Example:

{
  "success": true,
  "message": "Password reset successfully"
}
POST/api/v1/auth/verify-email

Verify Email

Verify email address using verification token.

Request Body Example:

{
  "token": "verification_token_here"
}

Response Example:

{
  "success": true,
  "message": "Email verified successfully"
}
POST/api/v1/auth/verify-email/resend

Resend Verification Email

Resend email verification link.

Request Body Example:

{
  "email": "user@example.com"
}

Response Example:

{
  "success": true,
  "message": "Verification email sent"
}

Agents Endpoints

GET/api/v1/agents

List Agents

Retrieve a list of all agents for the authenticated company.

Query Parameters:

limit: Number of results per page
offset: Pagination offset
status: Filter by status: active, inactive

Response Example:

{
  "agents": [
    {
      "agent_id": "agent_123",
      "name": "Customer Support Agent",
      "type": "customer_support",
      "status": "active",
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "total": 10,
  "limit": 20,
  "offset": 0
}
POST/api/v1/agents

Create Agent

Create a new AI agent with specified configuration.

Request Body Example:

{
  "name": "Sales Assistant",
  "type": "sales",
  "description": "Helps with sales inquiries",
  "model": "gpt-4",
  "temperature": 0.7,
  "max_tokens": 1000
}

Response Example:

{
  "agent": {
    "agent_id": "agent_456",
    "name": "Sales Assistant",
    "type": "sales",
    "status": "active",
    "created_at": "2025-01-15T10:00:00Z"
  }
}
GET/api/v1/agents/:agent_id

Get Agent

Retrieve detailed information about a specific agent.

Response Example:

{
  "agent": {
    "agent_id": "agent_123",
    "name": "Customer Support Agent",
    "type": "customer_support",
    "configuration": {
      "model": "gpt-4",
      "temperature": 0.7
    },
    "data_sources": [
      "ds_1",
      "ds_2"
    ],
    "created_at": "2025-01-15T10:00:00Z"
  }
}
POST/api/v1/agents/:agent_id/execute

Execute Agent

Execute an agent with input and receive AI-generated response.

Request Body Example:

{
  "input": "What are my recent orders?",
  "model": "gpt-4",
  "output_format": "json",
  "outlet_id": "outlet_123"
}

Response Example:

{
  "response": "Here are your recent orders...",
  "execution_id": "exec_789",
  "tokens_used": 150,
  "data_sources_queried": [
    "ds_1"
  ],
  "execution_time_ms": 1250
}
PUT/api/v1/agents/:agent_id

Update Agent

Update an existing agent configuration.

Request Body Example:

{
  "name": "Updated Sales Assistant",
  "description": "Updated description",
  "config": {}
}

Response Example:

{
  "agent": {
    "agent_id": "agent_123",
    "name": "Updated Sales Assistant",
    "updated_at": "2025-01-15T10:00:00Z"
  }
}
DELETE/api/v1/agents/:agent_id

Delete Agent

Delete an agent.

Response Example:

{
  "success": true,
  "message": "Agent deleted"
}
GET/api/v1/agents/:agent_id/preview

Preview Agent

Get agent preview configuration and UI settings.

Response Example:

{
  "agent": {
    "agent_id": "agent_123",
    "name": "Sales Assistant",
    "config": {},
    "ui_settings": {}
  }
}
POST/api/v1/agents/:agent_id/preview/test

Test Agent Preview

Test agent execution without billing (preview mode).

Request Body Example:

{
  "input": "Test query"
}

Response Example:

{
  "response": "Test response",
  "preview": true
}
GET/api/v1/agents/:agent_id/executions

Get Agent Executions

Get execution history for an agent.

Query Parameters:

limit: Number of results
offset: Pagination offset

Response Example:

{
  "executions": [
    {
      "execution_id": "exec_123",
      "input": "Query",
      "response": "Response",
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "total": 10
}
POST/api/v1/agents/:agent_id/chat

Chat with Agent

Chat with an agent (public endpoint for deployed agents).

Request Body Example:

{
  "message": "Hello",
  "conversation_id": "conv_123"
}

Response Example:

{
  "response": "Hello! How can I help you?",
  "conversation_id": "conv_123"
}

Data Sources Endpoints

GET/api/v1/data-sources

List Data Sources

Retrieve all data sources connected to the company.

Response Example:

{
  "data_sources": [
    {
      "connection_id": "ds_123",
      "source_name": "MySQL Database",
      "source_type": "mysql",
      "status": "connected",
      "created_at": "2025-01-15T10:00:00Z"
    }
  ]
}
POST/api/v1/data-sources/connect

Connect Data Source

Connect a new data source (database, API, file).

Request Body Example:

{
  "source_name": "Production Database",
  "source_type": "database",
  "mode": "online",
  "connection_config": {
    "type": "mysql",
    "host": "db.example.com",
    "port": 3306,
    "database": "mydb",
    "username": "user",
    "password": "password"
  },
  "test_connection": true
}

Response Example:

{
  "data_source": {
    "connection_id": "ds_123",
    "source_name": "Production Database",
    "source_type": "database",
    "status": "connected",
    "created_at": "2025-01-15T10:00:00Z"
  }
}
GET/api/v1/data-sources/:connection_id

Get Data Source

Retrieve detailed information about a specific data source.

Response Example:

{
  "data_source": {
    "connection_id": "ds_123",
    "source_name": "Production Database",
    "source_type": "database",
    "status": "connected",
    "connection_config": {}
  }
}
PUT/api/v1/data-sources/:connection_id

Update Data Source

Update data source configuration or schema.

Request Body Example:

{
  "source_name": "Updated Database",
  "connection_config": {}
}

Response Example:

{
  "data_source": {
    "connection_id": "ds_123",
    "source_name": "Updated Database"
  }
}
DELETE/api/v1/data-sources/:connection_id

Delete Data Source

Delete a data source connection.

Response Example:

{
  "success": true,
  "message": "Data source deleted"
}
POST/api/v1/data-sources/:connection_id/test-connection

Test Data Source Connection

Test the connection to a data source.

Response Example:

{
  "connected": true,
  "message": "Connection successful",
  "latency_ms": 50
}
POST/api/v1/data-sources/upload

Upload File Data Source

Upload a file to create an offline data source.

Request Body Example:

{}

Response Example:

{
  "data_source": {
    "connection_id": "ds_123",
    "source_name": "My File",
    "source_type": "file",
    "status": "connected"
  }
}
POST/api/v1/data-sources/query

Query Data Source

Execute a query against a data source.

Request Body Example:

{
  "connection_id": "ds_123",
  "query": "SELECT * FROM users LIMIT 10"
}

Response Example:

{
  "results": [],
  "row_count": 10,
  "execution_time_ms": 50
}

Deployments Endpoints

GET/api/v1/deployments

List Deployments

Retrieve all deployments for the authenticated company.

Query Parameters:

limit: Number of results
offset: Pagination offset

Response Example:

{
  "deployments": [
    {
      "deployment_id": "dep_123",
      "agent_id": "agent_123",
      "platform": "whatsapp",
      "status": "active",
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "total": 10
}
POST/api/v1/deployments/messaging

Deploy to Messaging Platform

Deploy an agent to a messaging platform (WhatsApp, Telegram, etc.).

Request Body Example:

{
  "agent_id": "agent_123",
  "platform": "whatsapp",
  "config": {}
}

Response Example:

{
  "deployment": {
    "deployment_id": "dep_123",
    "agent_id": "agent_123",
    "platform": "whatsapp",
    "status": "active"
  }
}
POST/api/v1/deployments/ecommerce

Deploy to E-commerce Platform

Deploy an agent to an e-commerce platform (Shopify, WooCommerce, etc.).

Request Body Example:

{
  "agent_id": "agent_123",
  "platform": "shopify",
  "config": {}
}

Response Example:

{
  "deployment": {
    "deployment_id": "dep_123",
    "agent_id": "agent_123",
    "platform": "shopify",
    "status": "active"
  }
}
GET/api/v1/deployments/:deployment_id

Get Deployment

Retrieve detailed information about a deployment.

Response Example:

{
  "deployment": {
    "deployment_id": "dep_123",
    "agent_id": "agent_123",
    "platform": "whatsapp",
    "status": "active",
    "config": {}
  }
}
PUT/api/v1/deployments/:deployment_id

Update Deployment

Update deployment configuration.

Request Body Example:

{
  "config": {}
}

Response Example:

{
  "deployment": {
    "deployment_id": "dep_123",
    "config": {}
  }
}
DELETE/api/v1/deployments/:deployment_id

Delete Deployment

Delete a deployment.

Response Example:

{
  "success": true,
  "message": "Deployment deleted"
}

Billing Endpoints

GET/api/v1/billing/subscription

Get Subscription

Retrieve current subscription details.

Response Example:

{
  "subscription": {
    "plan": "enterprise",
    "status": "active",
    "current_period_end": "2025-02-15T00:00:00Z",
    "credits_remaining": 10000
  }
}
GET/api/v1/billing/usage

Get Usage

Retrieve usage statistics and metrics.

Query Parameters:

start_date: Start date for usage period (ISO format)
end_date: End date for usage period (ISO format)
group_by: Group by: day, week, month

Response Example:

{
  "usage": {
    "total_requests": 5000,
    "total_tokens": 1000000,
    "total_cost": 50,
    "by_operation": {
      "agent_execute": 3000,
      "data_query": 2000
    }
  }
}
GET/api/v1/billing/credits

Get Credits

Check remaining credits balance.

Response Example:

{
  "credits": 10000,
  "total_credits": 50000,
  "used_credits": 40000
}
POST/api/v1/billing/credits/topup

Top Up Credits

Purchase additional credits.

Request Body Example:

{
  "amount": 1000,
  "payment_method_id": "pm_123"
}

Response Example:

{
  "credits": 11000,
  "transaction_id": "txn_123"
}
GET/api/v1/billing/invoices

List Invoices

Retrieve billing invoices.

Query Parameters:

limit: Number of results
offset: Pagination offset

Response Example:

{
  "invoices": [
    {
      "invoice_id": "inv_123",
      "amount": 100,
      "status": "paid",
      "created_at": "2025-01-15T10:00:00Z"
    }
  ]
}
GET/api/v1/billing/payment-methods

List Payment Methods

Retrieve saved payment methods.

Response Example:

{
  "payment_methods": [
    {
      "id": "pm_123",
      "type": "card",
      "last4": "4242",
      "brand": "visa"
    }
  ]
}

Account Endpoints

GET/api/v1/account/profile

Get Profile

Retrieve user profile information.

Response Example:

{
  "user": {
    "id": "user_id",
    "email": "user@example.com",
    "full_name": "John Doe",
    "role": "admin",
    "company_id": "company_id"
  }
}
POST/api/v1/account/api-keys

Create API Key

Generate a new API key for programmatic access.

Request Body Example:

{
  "name": "Production Integration",
  "permissions": [
    "read",
    "write"
  ]
}

Response Example:

{
  "api_key": {
    "id": "key_123",
    "name": "Production Integration",
    "key": "cv_live_abc123...",
    "created_at": "2025-01-15T10:00:00Z"
  }
}
GET/api/v1/account/api-keys

List API Keys

Retrieve all API keys for the current user.

Response Example:

{
  "api_keys": [
    {
      "id": "key_123",
      "name": "Production Integration",
      "created_at": "2025-01-15T10:00:00Z",
      "last_used": "2025-01-15T10:00:00Z"
    }
  ]
}
DELETE/api/v1/account/api-keys/:key_id

Delete API Key

Delete an API key.

Response Example:

{
  "success": true,
  "message": "API key deleted"
}

Companies Endpoints

GET/api/v1/companies/:company_id

Get Company

Retrieve company information.

Response Example:

{
  "company": {
    "id": 1,
    "name": "Example Corp",
    "created_at": "2025-01-15T10:00:00Z"
  }
}
GET/api/v1/companies/:company_id/users

List Company Users

Retrieve all users in a company.

Query Parameters:

q: Search query

Response Example:

{
  "users": [
    {
      "id": "user_123",
      "email": "user@example.com",
      "full_name": "John Doe",
      "role": "admin"
    }
  ]
}
GET/api/v1/companies/:company_id/outlets

List Company Outlets

Retrieve all outlets for a company.

Response Example:

{
  "outlets": [
    {
      "outlet_id": "outlet_123",
      "name": "Main Store",
      "address": "123 Main St"
    }
  ]
}

Webhooks Endpoints

GET/api/v1/webhooks

List Webhooks

Retrieve all webhooks for the company.

Response Example:

{
  "webhooks": [
    {
      "webhook_id": "wh_123",
      "url": "https://example.com/webhook",
      "events": [
        "agent.execute"
      ],
      "status": "active"
    }
  ]
}
POST/api/v1/webhooks

Create Webhook

Create a new webhook.

Request Body Example:

{
  "url": "https://example.com/webhook",
  "events": [
    "agent.execute"
  ]
}

Response Example:

{
  "webhook": {
    "webhook_id": "wh_123",
    "url": "https://example.com/webhook",
    "events": [
      "agent.execute"
    ],
    "status": "active"
  }
}

System Endpoints

GET/api/v1/health

Health Check

Check API health status.

Response Example:

{
  "status": "ok",
  "timestamp": "2025-01-15T10:00:00Z",
  "database": {
    "connected": true
  },
  "data": {
    "responsive": true
  }
}
GET/api/v1/utils/industries

Get Industries

Retrieve list of supported industries.

Response Example:

{
  "industries": [
    "Technology",
    "Healthcare",
    "Finance"
  ]
}

Rate Limits

Starter
1,000 requests/hour
1K/hr
Growth
10,000 requests/hour
10K/hr
Enterprise
Custom limits
∞

Rate limit information is included in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Error Handling

All errors follow a consistent format. Check the HTTP status code and error response body for details.

{
  "error": true,
  "message": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": {
    "field": "Additional error details"
  }
}
INVALID_REQUEST400 - Request validation failed
UNAUTHORIZED401 - Authentication required
FORBIDDEN403 - Insufficient permissions
NOT_FOUND404 - Resource not found
RATE_LIMIT_EXCEEDED429 - Too many requests