Creating Assets via External API

Creating Assets

Assets are the core insight unit of Spartera — named, versioned pieces of analytical logic that run against your connected data and return a single insight via API. This guide covers everything from initial creation through publishing to the marketplace.

If you need to return multiple rows of structured data (like a normal REST API response), you want an endpoint instead.

Asset Types

Calculation

Returns a single computed value — a number, a string, a percentage, a label. Examples: a churn rate (4.2), a top-performing region ("New York"), a customer satisfaction score (87).

If your query returns multiple rows or columns, you don't have a calculation asset — you have an endpoint.

Visualization

Returns chart-ready data paired with a chart type. Spartera renders the result as an interactive chart. Supported chart types: Bar, Line, Pie, Scatter, Area, Heatmap.

Note: Visualization assets cannot be created using External API connections. External API connections support Calculation assets only.

Asset Source

Every asset has a source type shown in the form header:

Manual — You created this asset directly via the Seller Dashboard or API.

AI Generated — Created by AutoInsights from your database schema. AI-generated assets require approval from a team admin before they can be used in the marketplace. See Approval Workflow below.

Required Fields

Field	Description
`name`	Unique, descriptive name for the asset
`description`	What the asset returns and what business question it answers
`connection_id`	Which database connection to use
`asset_type`	`CALCULATION` or `VISUALIZATION`
`sql_logic`	The SQL query (Calculation, non-External API)
`schema_table`	The table to use (Visualization)

Save vs Save Schema

The asset form has two separate save actions:

Save — Saves the asset's metadata: name, description, tags, industry, marketplace settings, restrictions, etc. Use this whenever you change any of these fields.

Save Schema — Saves the parameter schema that defines what inputs buyers can pass to the asset. This is what enables dynamic filtering and personalization. Required before buyers can customize executions.

Save Schema is disabled until:

An asset type is selected
SQL Logic is provided (for Calculation assets)
Schema/Table is specified (for Visualization assets)

Save Schema is not available for External API + Calculation assets — the schema is defined through the parameter editor instead.

SQL Logic

For standard database connections, write the SQL query that powers your asset. Spartera executes this against your connected database at execution time.

-- Example: Monthly churn rate — returns ONE value
SELECT
  ROUND(
    COUNT(CASE WHEN status = 'churned' THEN 1 END) * 100.0 / COUNT(*),
    2
  ) AS churn_rate_pct
FROM customers
WHERE created_at >= DATE_SUB(CURRENT_DATE, INTERVAL 12 MONTH)

SQL validation is skipped for:

External API connections (no SQL involved)
Visualization assets (schema-based, not SQL-based)

External API Assets

For External API connections (engine ID 20), assets work differently:

No SQL logic — Spartera calls your API endpoint instead
Function ID (optional) — Routes requests to specific models or functions at your endpoint
Schema parameters — Define typed inputs buyers provide before execution

Function ID

The Function ID is an optional routing identifier appended to your API call:

GET requests: Appended to the URL path — https://your-api.com/predict/forecast_model
POST requests: Included as a top-level key in the JSON body — {"function_id": "forecast_model", ...parameters}

Leave blank to use the base endpoint URL for all executions.

Example Function IDs:

weather_prediction
sales_forecast
churn_v2
model_v3

Schema Parameters

Schema parameters define the typed inputs buyers provide when executing your asset. Each parameter has:

Property	Description
`name`	Internal parameter name
`column_alias`	Display name shown to buyers
`type`	`STRING`, `INTEGER`, `FLOAT`, `BOOLEAN`, `DATE`, `TIMESTAMP`
`description`	What this parameter controls
`placeholder_text`	Example value shown to buyers
`valid_values`	Optional list of allowed values (renders as dropdown)

When valid_values are defined, buyers see a dropdown instead of a free-text field. Use this for parameters like region, segment, or category where a fixed set of options applies.

Type validation enforced at execution:

INTEGER — Must be a valid whole number
FLOAT — Must be a valid decimal number
BOOLEAN — true or false
DATE — YYYY-MM-DD format
TIMESTAMP — ISO 8601 format (YYYY-MM-DDTHH:MM:SS)

Marketplace Settings

Toggle Sell in Marketplace to make your asset available for purchase. When enabled, additional configuration appears:

Stripe Requirement

Your company must have a connected, fully-verified Stripe account before any product can be listed in the marketplace. If Stripe is not set up, the marketplace toggle is blocked.

Only company admins can connect Stripe. If you don't see the Marketplace Settings panel on your Account page, ask your company admin.

→ See Connecting Stripe for Payouts for the full setup guide.

Price

Set your per-execution price in USD. Spartera converts this to credits for buyers. You earn 80% of each transaction.

Require Customization

When enabled, buyers must customize the asset (fill in parameters) before they can purchase and execute it. Use this when your asset has required parameters that must be set per-buyer context — for example, a model that requires a customer segment or date range.

Asset Metadata

When selling in the marketplace, complete these additional fields to help buyers understand your data:

Time Period — The date range your data covers. Helps buyers understand historical coverage.

Geographic Coverage — Which regions, countries, or markets this asset covers.

Data Refresh Frequency — How often your underlying data is updated (real-time, daily, weekly, monthly, etc.). Buyers use this to understand how current the results are.

Price History

Every price change is recorded. The asset form shows a price history table with the active price highlighted. Price changes take effect immediately for new executions.

Security Restrictions

Domain Restrictions

Block specific email domains from accessing your asset. Leave empty to allow all users.

Enter domains in the domain restrictions input (e.g., competitor.com). Multiple domains are stored as a semicolon-separated list internally.

Rate Limiting

Control how frequently users can call your asset. All three fields must be configured for rate limiting to take effect — partial configuration has no effect.

Field	Options	Description
Request Limit	1–10,000	Number of requests allowed per time window
Period	SECOND, MINUTE, HOUR, DAY	The time window
Scope	USER, COMPANY, IP, GLOBAL	Who shares the same rate limit bucket

Scope options:

USER — Each buyer gets their own independent limit
COMPANY — All users in a buyer's company share one limit
IP — Rate limited by client IP address
GLOBAL — All requests to the asset share one limit regardless of who made them

Example configurations:

Use Case	Request Limit	Period	Scope
Interactive dashboard	60	MINUTE	USER
Batch analytics	1,000	HOUR	COMPANY
High-security model	10	MINUTE	IP
Abuse prevention	5,000	DAY	GLOBAL

Approval Workflow

AI-generated assets (created via AutoInsights) require admin approval before they appear in the marketplace or can be used externally.

Approval Statuses

Status	Meaning
PENDING	Awaiting review by a team admin
APPROVED	Cleared for marketplace use
REJECTED	Rejected by admin, needs attention
NEEDS_REVISION	Admin has requested changes

Who Can Approve

Users with a role above Analyst (role > 1) see approval controls in the asset form header and can:

Approve — Clear the asset for marketplace use
Needs Revision — Request changes from the creator
Reject — Block the asset from marketplace use
Revoke Approval — Pull back a previously approved asset

Analysts see a read-only "Awaiting Approval" status chip and cannot modify approval state.

Manually Created Assets

Assets you create manually do not go through the approval workflow — they are ready to publish immediately after creation and testing.

Asset Lifecycle

Draft → Tested → Published → Active (earning revenue)
         │
         └─► Archived (removed from marketplace)

Stage	Description
Draft	Asset created but not yet validated
Tested	Preview execution completed successfully
Published	Live in marketplace, buyers can purchase and execute
Archived	Removed from marketplace

Best Practices

Return one thing. A calculation asset should return a single value. If you find yourself returning multiple columns or rows, you probably want an endpoint instead.

Write great descriptions. Buyers can't see your SQL or your model. A clear description of what the asset returns, what data it uses, and how fresh the data is directly affects conversion on the marketplace.

Optimize for performance. Your SQL or API runs on someone else's schedule. Target sub-500ms execution for simple queries, under 5 seconds for complex analytics.

Set valid_values where applicable. If a parameter only accepts specific inputs (regions, segments, statuses), define valid_values to give buyers a dropdown instead of a free-text field. This prevents invalid executions.

Use domain restrictions proactively. If you're selling industry-specific data, restrict competitor domains from accessing your assets.

Test before publishing. Always run a preview execution against real data before publishing. Sample data hides edge cases.

Assets Overview — Asset types, lifecycle, and key concepts
Endpoints Overview — When you need rowset data instead of a single value
Testing and Validation — How preview mode and parameter testing work
Publishing to Marketplace — Going live and getting discovered
Connecting Stripe for Payouts — Required for any seller
External API Connections — Building assets on top of ML model endpoints
Credit System — How pricing and payouts work