External API Connections

External API connections link Spartera directly to an HTTPS API — either your own service or a third-party data provider. They serve two distinct purposes, which you choose with the API Type field when creating the connection:

Managed Calculation (request_format: STRUCTURED) — Spartera calls your API to compute a single value, such as an ML model prediction. Sold as a Calculation asset. Your model and logic run on your own infrastructure; Spartera only sees the response.
Data Feed Passthrough (request_format: PASSTHROUGH) — Spartera calls a data API, repackages the response into rows you configure, and resells it as a Data endpoint. Ideal for value-added reselling of third-party data APIs (search results, market data, enrichment feeds).

API Type determines product type. A Managed Calculation connection can back Calculation assets only. A Data Feed Passthrough connection can back Data endpoints only. You select the type once, on the connection, and Spartera enforces the pairing in the asset and endpoint builders.

When to Use External API

Use engine ID 20 when:

You have a trained ML model deployed as a REST API and want to sell its predictions (Managed Calculation)
Your analytical logic runs on your own servers and you want to expose it through Spartera (Managed Calculation)
You have a licensed third-party data API and want to package and resell it in the marketplace (Data Feed Passthrough)

If your data lives in a database, use a standard database connection and write SQL-based assets or endpoints instead.

The Two API Types

Managed Calculation (`STRUCTURED`)

Your API implements Spartera's request/response contract: Spartera sends a structured request, your server computes a result, and returns it in the Spartera response format (an answer_value with a timestamp). Spartera extracts the value and returns it to the buyer. Designed for predictive analytics: churn prediction, fraud detection, price optimization, credit scoring, demand forecasting.

Data Feed Passthrough (`PASSTHROUGH`)

Spartera calls the provider's API in the format the provider expects, then repackages the response. You don't implement Spartera's contract — instead you configure, on the endpoint, a request template (the body Spartera sends upstream, with {placeholder} slots) and a set of fields tagged as request (sent to the provider) or response (returned to the buyer). Spartera fills the template from buyer input and seller-fixed values, calls the provider, extracts the rows, and projects the fields you expose. No aggregation is applied — the response is repackaged, not queried.

Requirements

Before connecting, the API must:

Be accessible over HTTPS — HTTP is not supported
Be publicly accessible or reachable from Spartera's IP (34.70.197.249)
For Managed Calculation: return responses that conform to the Spartera response format
Support API key authentication (recommended)

Required Fields

In addition to the standard connection fields, External API connections require:

Field	Description	Example
`api_endpoint`	Full HTTPS URL Spartera will call	`https://api.yourcompany.com/predict`
`http_method`	`GET` or `POST`	`POST`
`request_format`	API Type: `STRUCTURED` (Calculation) or `PASSTHROUGH` (Data Feed)	`PASSTHROUGH`
`api_key_location`	Where the key is sent: `HEADER`, `URL`, or `BEARER`	`BEARER`
`api_key_param`	Name of the API key parameter (not used for `BEARER`)	`X-API-Key`
`credentials`	Your actual API key or token (encrypted at rest)	`sk-live-abc123...`
`provider_domain`	Domain where the API lives	`api.yourcompany.com`

Field name: the API key location field is api_key_location (with underscores). Older examples that used apikey_location were incorrect.

Creating the Connection

Via Dashboard

app.spartera.com → Connections → New Connection → External / Data API

Select the API Type (Managed Calculation or Data Feed Passthrough), enter the endpoint and credentials, and save.

Via API — Managed Calculation

connection = connections.companies_company_id_connections_post(
    company_id,
    {
        "company_id": "your-company-id",
        "user_id": "your-user-id",
        "engine_id": 20,
        "name": "Customer Churn Predictor",
        "description": "Production churn prediction model. Returns churn probability (0-1).",
        "provider_domain": "api.yourcompany.com",
        "credential_type": "API_KEY",
        "api_endpoint": "https://api.yourcompany.com/predict/churn",
        "http_method": "POST",
        "request_format": "STRUCTURED",
        "api_key_location": "HEADER",
        "api_key_param": "X-API-Key",
        "credentials": "your-api-key-here",
        "verified_usage_ability": True
    }
)

Via API — Data Feed Passthrough

connection = connections.companies_company_id_connections_post(
    company_id,
    {
        "company_id": "your-company-id",
        "user_id": "your-user-id",
        "engine_id": 20,
        "name": "SERP Data API",
        "description": "Search results data API, repackaged and resold as an endpoint.",
        "provider_domain": "api.provider.com",
        "credential_type": "API_KEY",
        "api_endpoint": "https://api.provider.com/request",
        "http_method": "POST",
        "request_format": "PASSTHROUGH",
        "api_key_location": "BEARER",
        "credentials": "your-bare-api-key",
        "verified_usage_ability": True
    }
)

Note the passthrough example uses api_key_location: "BEARER" and omits api_key_param — see below.

API Key Location Options

HEADER

The key is sent as a custom request header whose name you specify in api_key_param.

curl -X POST https://api.yourcompany.com/predict \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"segment": "enterprise"}'

BEARER

The key is sent in the standard Authorization header as a bearer token — the format used by most modern commercial APIs (Stripe, OpenAI, and many data providers). Store the bare key in the credentials field; Spartera adds the Bearer prefix automatically. The api_key_param field is not used for BEARER (the header name is always Authorization).

curl -X POST https://api.provider.com/request \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "..."}'

URL

The key is appended as a query parameter. Less secure — avoid for sensitive keys.

https://api.yourcompany.com/predict?api_key=your-api-key

HTTP Method

POST — Use for model inference endpoints and data APIs that accept input in a JSON body. Most ML and data APIs use POST.

GET — Use for read-only endpoints where parameters are passed as query strings.

Response Format

For Managed Calculation connections, your API must return a response Spartera can parse. See the full Response Schema Specifications.

For Data Feed Passthrough connections, there is no fixed response contract — you configure how the provider's response is extracted and projected on the endpoint itself.

IP Whitelisting

If the API is behind a firewall, whitelist Spartera's production IP: 34.70.197.249

Google Cloud:

gcloud compute firewall-rules create allow-spartera \
  --allow tcp:443 \
  --source-ranges 34.70.197.249/32

AWS Security Group:

aws ec2 authorize-security-group-ingress \
  --group-id sg-xxxxx \
  --protocol tcp \
  --port 443 \
  --cidr 34.70.197.249/32

nginx:

location /predict {
    allow 34.70.197.249;
    deny all;
}

Testing Your Connection

After saving, click Test Connection. Spartera sends a test request and verifies HTTPS connectivity, authentication, and (for Managed Calculation) response format.

Data Feed Passthrough: the Test Connection button validates the Managed Calculation contract, so it is not a meaningful signal for passthrough connections. Validate a passthrough connection by running a pull through the endpoint you build on it.

Common Test Failures

Error	Cause	Fix
Timeout	API not publicly reachable	Check firewall rules and URL
401 Unauthorized	Wrong key, header name, or missing `Bearer` prefix	Verify `api_key_location` and credentials
SSL certificate error	Expired or invalid certificate	Use Let's Encrypt for a valid cert
Invalid response format	Response doesn't match Spartera format (Managed Calculation)	Review Response Schema Specifications

Multiple Models on One Connection

For Managed Calculation, if you have multiple model endpoints:

Separate connections — One connection per model, each with its own URL and key. Simpler to manage.

Function ID routing — One connection with a base URL, different Function IDs route to different endpoints. Better for a fleet of related models. See Function ID Routing.

Security Best Practices

Prefer BEARER or HEADER for API key location — avoid URL for sensitive keys
Create a dedicated API key for Spartera — don't reuse keys from other systems
Rotate keys regularly — update in Spartera after rotating in your system
Add rate limiting to protect your API from unexpected traffic

Timeout Guidelines

Default timeout is 30 seconds. For complex models:

Model Type	Recommended Timeout
Fast inference (sub-1s)	5 seconds
Standard models	30 seconds
Complex analytics	60 seconds
Batch processing	120 seconds

Connecting Your API — Full step-by-step setup guide
Response Schema Specifications — Required API response format (Managed Calculation)
Function ID Routing — Route multiple models via one connection
Creating Assets — Build calculation assets on a Managed Calculation connection
Endpoints Overview — Build data endpoints on a Data Feed Passthrough connection
IP Whitelisting — Full IP whitelisting reference