Endpoints Overview

A Spartera Endpoint is a managed data API exposed directly from your database. Configure it once — the column subset, aggregations, filters, rate limits — and Spartera handles the rest: authentication, pagination, billing, and customer key management.

Endpoints are how data providers package and sell rowset data to customers and AI agents through a clean RESTful interface. Buyers integrate them like any other API.

When to Use an Endpoint vs an Asset

The two product types are distinguished by the shape of the response:

You want to return...	Use a...
A single value or insight (a number, a string, a percentage)	Calculation Asset
A chart or graph (PNG/SVG)	Visualization Asset
Multiple rows of structured data (like a normal REST API)	Endpoint

If a buyer asks "what's the average air distance for an NFL quarterback?", the answer is a single number — that's an asset. If they ask "give me air distance per quarterback", the answer is rows — that's an endpoint.

How Endpoints Work

When a buyer calls your endpoint, here's what happens:

Spartera validates the API key and confirms it's scoped to this endpoint
Spartera connects to your database via your stored credentials
Your endpoint's SQL — generated at runtime from your column configuration — executes inside your database
Results are paginated, JSON-serialized, and wrapped in the standard envelope
Credits are deducted from the buyer's balance only on a successful 200 OK

Raw data never leaves your database except as the rows being returned. There's no replication, no copy, no syncing.

The Response Envelope

Every endpoint response has the same three-part shape:

{
  "message": "success",
  "data": {
    "spartera": {
      "request_id": "d23e815b-a490-495a-8b07-4eee717f2d08",
      "billed": true,
      "credits_consumed": 2,
      "page": 1,
      "page_size": 100,
      "total_returned": 37,
      "has_more": false,
      "next_start": null,
      "next_page": null
    },
    "request": {
      "endpoint": "first-nfl-nextgen-advanced-stats",
      "endpoint_id": "a72b8513-a6e8-4b38-9982-3ccd0d64339a",
      "limit": 100,
      "params": {},
      "source": "nflverse.com",
      "start": 0
    },
    "response": {
      "data": [
        { "team": "ARI", "first_name": "Kyler", "last_name": "Murray", "median_avg_air_distance": 19.04 },
        { "team": "MIA", "first_name": "Tua", "last_name": "Tagovailoa", "median_avg_air_distance": 20.65 }
      ]
    }
  }
}

Block	What's in it
`spartera`	Request metadata, billing info, pagination state
`request`	Echo of what the buyer asked for (slug, params, pagination cursor)
`response.data`	The rows themselves

Endpoint Lifecycle

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

Stage	Description
Draft	Endpoint created but not yet validated
Tested	Sample preview executed successfully
Published	Live in marketplace, buyers can subscribe and fetch
Inactive	Removed from marketplace; existing buyer keys revoked

Key Properties of Every Endpoint

Property	Required	Description
`name`	✅	Human-readable name (shown in marketplace)
`description`	✅	What rows the endpoint returns
`connection_id`	✅	Which database connection to query
`source_schema_name`	✅	Database schema where the source table lives
`source_table_name`	✅	Table being exposed
`endpoint_schema`	✅	Column-level config: which columns, aliases, aggregations, filters
`access_method`	✅	`OPEN`, `API_KEY`, or `IP` (most use `API_KEY`)
`max_records_per_request`		Seller-enforced row cap per request (default 1,000)
`rate_limit_number` + `rate_limit_period` + `rate_limit_granularity`		Optional per-buyer or per-IP rate limits
`sell_in_marketplace`		`true` = public listing; `false` = direct B2B only
`data_time_period_start` / `data_time_period_end`		When your data records begin/end
`data_source_refresh_frequency`		How often the source data updates

Pricing is set separately via the price history API — it lives on asset_price_history, not on the endpoint record itself.

Visibility & Access Control

Public (Marketplace)

Endpoint appears in marketplace search. Any buyer can subscribe (one click), receive a unique API key scoped to their company, and fetch data. You earn 80% of every paid request.

B2B / Direct (Manual Key)

Endpoint can be private (sell_in_marketplace=false) or public but customer-specific. You manually mint endpoint keys for specific customers via the API Key Management UI on the endpoint edit page. Useful for contracts negotiated outside the marketplace.

Internal (Same Company)

Members of your own company can fetch data from your endpoints without minting keys, using their session or analytics key. No credits charged.

Per-Buyer Key Provisioning

When a buyer fetches data from your endpoint via the marketplace for the first time, Spartera auto-provisions an endpoint key scoped to:

Their company (so usage and billing attribute correctly)
Your endpoint (so the key only works for this one resource)

The buyer can use that key inside the marketplace UI or copy it out to call the endpoint from their own apps, agents, or scripts. Each buyer gets their own unique key — revoking one customer doesn't affect any others.

→ See API Keys for the full key model.

Best Practices

Use sensible row caps. Set max_records_per_request based on what your underlying database can comfortably return in a single query. Default is 1,000.

Configure aggregations server-side. When buyers want pre-aggregated data (sums, averages, percentiles, date rollups), set the aggregation in the column config rather than asking buyers to compute it themselves. This both improves performance and reduces row volume.

Set realistic refresh frequency. Buyers care about data freshness. Misrepresenting it is the most common cause of buyer complaints.

Test with the Preview button. The seller-side "Preview / Test" button runs your endpoint against real data with a limited row count and shows the exact JSON shape buyers will receive. Use this before publishing.

Add top questions. The optional top_questions field lets you describe the buyer-facing semantic value of the data ("How does air distance vary by quarterback?"). These power Vertex AI Search relevance and product-page SEO.

Endpoint API Reference — Customer-facing route, pagination, response envelope
API Keys — How endpoint keys work
Subscribing to Endpoints — Buyer-side flow
Credit System — How endpoint billing works
Publishing to Marketplace — Going live