API Overview

The Spartera API is a REST API that powers every action in the platform — creating assets and endpoints, managing connections, executing analytics, fetching data feeds, and handling marketplace operations. All requests authenticate via API key.

Two API Surfaces

The Spartera API is split into two surfaces with different base URLs and auth models:

1. Management API

For sellers (data providers) managing their resources, and for analytics asset execution.

Base URL:

https://api.spartera.com

Auth: Analytics API key (sk_spartera_...) in the x-api-key header.

Patterns:

https://api.spartera.com/companies/{company_id}/{resource}

Used for: creating endpoints, managing connections, running analytics assets, managing API keys, billing, and all other administrative actions.

2. Customer-Facing Endpoint API

For buyers fetching rowset data from endpoints.

Base URL (per seller):

https://{seller_handle}.api.spartera.com

Auth: Endpoint API key (ep_...) in the x-api-key header.

Pattern:

https://{seller_handle}.api.spartera.com/endpoints/v1/{endpoint_slug}

Used for: fetching data from a specific endpoint. See Endpoint API Reference.

Authentication

All requests require an API key in the x-api-key header. There are two key types:

Type	Prefix	Used For
Analytics	`sk_spartera_`	Management API — full CRUD, asset execution
Endpoint	`ep_`	Customer-facing endpoint API — data fetch only

→ See API Keys for the full key model, role hierarchy, and creation flows.

# Management API request — analytics key
curl https://api.spartera.com/companies/{company_id}/endpoints \
  -H "x-api-key: sk_spartera_..."

# Endpoint data fetch — endpoint key
curl "https://{seller_handle}.api.spartera.com/endpoints/v1/{endpoint_slug}" \
  -H "x-api-key: ep_..."

Getting Your Keys

Analytics keys:

Dashboard → Settings → API Keys → Generate New Key

Endpoint keys (as a buyer): Auto-provisioned the first time you click Fetch Data on a marketplace endpoint. See Subscribing to Endpoints.

Endpoint keys (as a seller, for B2B contracts):

Dashboard → Endpoints → [Your Endpoint] → API Key Management → Create Key

Key Visibility

Plain text values are only shown once at creation. Spartera stores only an HMAC of the key for validation — once you close the creation dialog, the original value is not recoverable. Save it immediately.

Key Best Practices

Use separate keys for development and production
Never commit API keys to source control — use environment variables
Rotate keys if they're ever exposed
Use the name field when creating keys to track which system uses which key
Use the lowest-privilege key role that gets the job done

Request Format

# Standard GET request
curl https://api.spartera.com/companies/{company_id}/assets \
  -H "x-api-key: sk_spartera_..." \
  -H "accept: application/json"

# POST with JSON body
curl -X POST https://api.spartera.com/companies/{company_id}/assets \
  -H "x-api-key: sk_spartera_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "My Asset", "asset_type": "CALCULATION"}'

# PATCH (partial update)
curl -X PATCH https://api.spartera.com/companies/{company_id}/assets/{asset_id} \
  -H "x-api-key: sk_spartera_..." \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description"}'

Response Formats

Management API

{
  "data": { },
  "meta": {
    "timestamp": "2025-04-01T13:00:00Z",
    "version": "1.0",
    "execution_time_ms": 142
  }
}

List endpoints include pagination metadata:

{
  "data": [...],
  "meta": {
    "total": 247,
    "page": 1,
    "per_page": 50,
    "has_next": true
  }
}

Customer-Facing Endpoint API

Endpoint responses use a three-block envelope:

{
  "message": "success",
  "data": {
    "spartera": { "request_id": "...", "billed": true, "credits_consumed": 2, ... },
    "request": { "endpoint": "...", "params": {...}, ... },
    "response": { "data": [ ...rows... ] }
  }
}

→ See Endpoint API Reference for the full envelope spec.

HTTP Status Codes

Code	Meaning
`200 OK`	Successful GET, PATCH, or endpoint fetch
`201 Created`	Successful POST — new resource created
`204 No Content`	Successful DELETE
`400 Bad Request`	Invalid request parameters
`401 Unauthorized`	Missing or invalid API key
`403 Forbidden`	Valid key but insufficient permissions
`404 Not Found`	Resource doesn't exist
`422 Unprocessable Entity`	Valid request but business logic error
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Spartera server error
`502 Bad Gateway`	Seller-side error (database unreachable, query timeout) — endpoints only
`503 Service Unavailable`	Endpoint not in `ACTIVE` status — endpoints only

Error Responses

Errors return a structured body. Management API:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your account does not have enough credits to execute this asset.",
    "details": {
      "required_credits": 5,
      "available_credits": 2,
      "asset_id": "asset_abc123"
    }
  }
}

Endpoint API errors include an error_source field indicating who's responsible (BUYER, SELLER, or SPARTERA):

{
  "message": "Insufficient credits. Required: 2, Available: 0",
  "data": {
    "error_type": "INSUFFICIENT_CREDITS",
    "error_source": "BUYER",
    "request_id": "..."
  }
}

Rate Limits

Endpoint Group	Limit
Authentication endpoints	1,000 requests/hour
Asset management	5,000 requests/hour
Asset execution	Based on your plan
Marketplace endpoints	10,000 requests/hour
Per-endpoint custom rate limits	Set by the seller

Rate limit headers are included on every response:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4872
X-RateLimit-Reset: 1743516000

Pagination

Management API

List endpoints support limit and offset parameters:

curl "https://api.spartera.com/companies/{company_id}/assets?limit=50&offset=50" \
  -H "x-api-key: sk_spartera_..."

Customer-Facing Endpoint API

Endpoint data uses start and limit cursors with next_start returned in each response. See Endpoint API Reference for examples.

SDK Support

Official SDKs are available:

Language	Install
Python	`pip install spartera-api-sdk`
JavaScript	`npm install spartera-js-sdk`

# Python SDK example
from spartera_api_sdk import ApiClient, Configuration
from spartera_api_sdk.api import assets_api

config = Configuration()
config.host = "https://api.spartera.com"
config.api_key = {'X-API-Key': 'sk_spartera_...'}

client = ApiClient(config)
assets = assets_api.AssetsApi(client)

# List all your assets
result = assets.companies_company_id_assets_get(company_id)

API Reference

Resource	Description
Authentication	Manage API keys and access
API Keys	Analytics keys vs endpoint keys, creation, rotation
Assets	Create, manage, and execute analytics assets
Endpoint API	Customer-facing data fetch route
Connections	Database connection management
Marketplace	Browse and purchase marketplace products
Users	User and team management
Billing	Credits, invoices, and payouts

OpenAPI Specification

Download the full OpenAPI spec to generate client code for any language:

curl https://api.spartera.com/openapi.yaml -o spartera-api.yaml

Or import directly into Postman, Insomnia, or your preferred API client.