REST API Examples

Direct access to the Spartera REST API using standard HTTP requests.
All endpoints support JSON request/response format with API key
authentication.

Base URL

https://api.spartera.com

Authentication

All API requests require authentication via the X-API-Key header:

curl -H "X-API-Key: your-api-key" \
     -H "Content-Type: application/json" \
     https://api.spartera.com/assets

Create Connection

Create a new data warehouse connection:

curl -X POST https://api.spartera.com/connections \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production BigQuery",
    "type": "bigquery",
    "credentials": {
      "project_id": "my-gcp-project",
      "credentials_json": "{\"type\":\"service_account\"...}"
    }
  }'

Response:

{
  "id": "conn-12345",
  "name": "Production BigQuery",
  "type": "bigquery",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

Create Asset

Create a new analytic asset:

curl -X POST https://api.spartera.com/assets \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Revenue Analysis",
    "type": "sql",
    "query": "SELECT customer_id, SUM(revenue) FROM orders GROUP BY customer_id",
    "connection_id": "conn-12345",
    "description": "Monthly customer revenue breakdown"
  }'

Response:

{
  "id": "asset-67890",
  "name": "Customer Revenue Analysis",
  "type": "sql",
  "connection_id": "conn-12345",
  "status": "draft",
  "created_at": "2024-01-15T11:00:00Z"
}

List Assets

Retrieve assets with pagination:

curl -X GET "https://api.spartera.com/assets?page=1&per_page=25&status=active" \
  -H "X-API-Key: your-api-key"

Response:

{
  "data": [
    {
      "id": "asset-67890",
      "name": "Customer Revenue Analysis",
      "type": "sql",
      "status": "active",
      "created_at": "2024-01-15T11:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "pages": 1
  }
}

Get Specific Asset

Retrieve asset details:

curl -X GET https://api.spartera.com/assets/asset-67890 \
  -H "X-API-Key: your-api-key"

Response:

{
  "id": "asset-67890",
  "name": "Customer Revenue Analysis",
  "type": "sql",
  "query": "SELECT customer_id, SUM(revenue) FROM orders GROUP BY customer_id",
  "connection_id": "conn-12345",
  "status": "active",
  "metadata": {
    "tags": ["revenue", "customers"],
    "category": "analytics"
  },
  "created_at": "2024-01-15T11:00:00Z",
  "updated_at": "2024-01-15T11:30:00Z"
}

Update Asset

Update asset properties:

curl -X PUT https://api.spartera.com/assets/asset-67890 \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enhanced Customer Revenue Analysis",
    "description": "Updated monthly customer revenue with segments",
    "metadata": {
      "tags": ["revenue", "customers", "segments"],
      "category": "analytics"
    }
  }'

Set Asset Pricing

Configure pricing strategy:

curl -X POST https://api.spartera.com/assets/asset-67890/pricing \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "strategy": "subscription",
    "price": 99.99,
    "currency": "USD",
    "billing_period": "monthly"
  }'

Publish to Marketplace

Publish asset to marketplace:

curl -X POST https://api.spartera.com/marketplace/publish \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "asset-67890",
    "public": true,
    "featured": false
  }'

Get Usage Analytics

Retrieve usage statistics:

curl -X GET "https://api.spartera.com/analytics/usage/asset-67890?start_date=2024-01-01&end_date=2024-01-31&granularity=daily" \
  -H "X-API-Key: your-api-key"

Response:

{
  "asset_id": "asset-67890",
  "period": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
  },
  "metrics": {
    "total_queries": 1250,
    "unique_users": 45,
    "total_revenue": 449.55
  },
  "daily_breakdown": [
    {
      "date": "2024-01-01",
      "queries": 32,
      "users": 8,
      "revenue": 12.50
    }
  ]
}

Get Performance Metrics

Retrieve performance data:

curl -X GET https://api.spartera.com/analytics/performance/asset-67890 \
  -H "X-API-Key: your-api-key"

Response:

{
  "asset_id": "asset-67890",
  "performance": {
    "avg_response_time": 245,
    "success_rate": 99.2,
    "error_rate": 0.8,
    "cache_hit_rate": 85.4
  },
  "last_updated": "2024-01-15T12:00:00Z"
}

Revenue Reporting

Get revenue reports:

curl -X GET "https://api.spartera.com/billing/revenue?start_date=2024-01-01&end_date=2024-01-31&group_by=asset" \
  -H "X-API-Key: your-api-key"

Response:

{
  "period": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
  },
  "total_revenue": 2847.50,
  "breakdown": [
    {
      "asset_id": "asset-67890",
      "asset_name": "Customer Revenue Analysis",
      "revenue": 449.55,
      "transactions": 1250
    }
  ]
}

Delete Asset

Remove an asset:

curl -X DELETE https://api.spartera.com/assets/asset-67890 \
  -H "X-API-Key: your-api-key"

Response:

{
  "success": true,
  "message": "Asset deleted successfully"
}

Error Handling

API errors return structured responses:

{
  "error": {
    "code": "ASSET_NOT_FOUND",
    "message": "Asset with ID 'invalid-id' not found",
    "status_code": 404
  }
}

Common HTTP Status Codes

200 - Success
201 - Created
400 - Bad Request
401 - Unauthorized (invalid API key)
404 - Not Found
422 - Validation Error
429 - Rate Limit Exceeded
500 - Internal Server Error

Rate Limiting

API requests are rate limited. Check response headers:

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

Filtering and Search

Many endpoints support filtering:

## Filter assets by type and status
curl -X GET "https://api.spartera.com/assets?type=sql&status=active&search=revenue" \
  -H "X-API-Key: your-api-key"

## Sort results
curl -X GET "https://api.spartera.com/assets?sort_by=created_at&order=desc" \
  -H "X-API-Key: your-api-key"