Craveva AI Enterprise - AI Enterprise Data Platform

Back to Documentation

API Reference

REST endpoints, authentication, and response formats for the Craveva AI platform.

Base URL

https://ai.craveva.com/api/v1

All API requests should be made to this base URL with the appropriate endpoint path.

Full API Reference: For complete API documentation with interactive playground, see API Reference.

Authentication

All API requests require authentication using an API key. Include your API key in the request headers.

Header Format

Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with your actual API key.

Getting Your API Key

Log in to your Craveva AI dashboard
Navigate to Account → API Keys
Click Generate New Key
Copy and store your API key securely (it's only shown once)

Security Note: Never commit API keys to version control or share them publicly. Store them securely using environment variables or secret management systems.

Request Format

HTTP Methods

GET - Retrieve resources
POST - Create resources
PUT - Update resources
PATCH - Partial updates
DELETE - Delete resources

Content-Type

All requests with a body must include:

Content-Type: application/json

Example Request

curl -X GET https://api.craveva.ai/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Format

All API responses are returned in JSON format.

Success Response

{
  "success": true,
  "data": {
    // Response data here
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z",
    "request_id": "req_123456"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // Additional error details
    }
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z",
    "request_id": "req_123456"
  }
}

HTTP Status Codes

200 - Success
201 - Created
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
429 - Too Many Requests
500 - Internal Server Error

Endpoints

Agents

GET/agents

List all agents

Query params: page, limit, category

GET/agents/{id}

Get agent by ID

POST/agents

Create a new agent

Body: name, description, data_source_id, config

PUT/agents/{id}

Update an agent

DELETE/agents/{id}

Delete an agent

POST/agents/{id}/execute

Execute an agent query

Body: query, context (optional)

Data Sources

GET/data-sources

List all data sources

GET/data-sources/{id}

Get data source by ID

POST/data-sources

Connect a new data source

Body: type, name, connection_config

POST/data-sources/{id}/test

Test data source connection

Deployments

GET/deployments

List all deployments

POST/deployments

Create a new deployment

Body: agent_id, platform, config

Usage & Billing

GET/billing/usage

Get usage statistics

Query params: start_date, end_date, agent_id

GET/billing/credits

Get current credit balance

Rate Limiting

API requests are rate-limited to ensure fair usage and system stability. Rate limits vary by plan:

Free Plan: 100 requests/hour
Pro Plan: 1,000 requests/hour
Enterprise: Custom limits

When rate limits are exceeded, you'll receive a 429 Too Many Requests response.

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Pagination

List endpoints support pagination using query parameters:

page - Page number (default: 1)
limit - Items per page (default: 20, max: 100)

Paginated responses include pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "total_pages": 5,
    "has_next": true,
    "has_prev": false
  }
}