01 / API Reference
Spearhead API documentation
Read-only JSON over HTTPS. Use one header: X-API-Key. Every response includes metadata for provenance, quality, and legal posture.
02 / Endpoints overview
Available endpoints
GET/v1/companiesList available companies and latest marks.
GET/v1/companies/{slug}Fetch one company profile and its latest mark.
GET/v1/companies/{slug}/marksHistoric marks with 80% band, optional 95% band.
GET/v1/companies/{slug}/eventsAppend-only event history for this company.
GET/v1/companies/{slug}/resolutionAudit bundle with signature for enterprise attestations.
GET/v1/usageCurrent key context and rate-limit state.
03 / Quickstart
Get started in 3 calls
- Start free checkout at /api/checkout?tier=research. You will receive a key after entitlement is active.
- Call /v1 with your API key in the
X-API-Keyheader. - Read the meta object before using values: check
data_modeandprovenancefor each response.
Quickstart callshell
export SPEARHEAD_API_KEY=sph_live_example_key
curl -sS "https://api.pegasusthreesixty.com/v1/companies?limit=1" \
-H "X-API-Key: $SPEARHEAD_API_KEY"Quality check before integration
Before using any value in a workflow, check the response meta fields and compare the public data quality card with your required coverage, freshness, licensing, and validation standards.
Competitive QA snapshot: 0 of 18 reviewed vendors publish walk-forward backtests. Spearhead keeps scorecard and miss disclosure in public routes by default.
04 / Authentication
Authentication
Send your key in the request header only:
X-API-Key: <your-key>
No OAuth and no query-string API keys are supported. Keys are tenant-scoped and tier-bound.
05 / Endpoint details
Endpoint examples
GET /v1/companiesResearch+
List available companies and latest marks.
Parameters: limit, cursor, sector, status, sort
Request - curlGET /v1/companies
curl "https://api.pegasusthreesixty.com/v1/companies?limit=50&sort=-value_usd" \
-H "X-API-Key: $SPEARHEAD_API_KEY"Request - PythonGET /v1/companies
import os, requests
resp = requests.get(
"https://api.pegasusthreesixty.com/v1/companies?limit=50&sort=-value_usd",
headers={"X-API-Key": os.environ["SPEARHEAD_API_KEY"]},
timeout=10,
)
resp.raise_for_status()
body = resp.json()
assert body["meta"]["data_mode"] in ("illustrative", "live")
print(body["slug"] if "slug" in body else "ok")Request - JavaScriptGET /v1/companies
const resp = await fetch("https://api.pegasusthreesixty.com/v1/companies?limit=50&sort=-value_usd", {
headers: { "X-API-Key": process.env.SPEARHEAD_API_KEY },
});
if (!resp.ok) throw new Error(`${resp.status} ${await resp.text()}`);
const body = await resp.json();
console.log(body.meta.data_mode);Request - GoGET /v1/companies
req, _ := http.NewRequest("GET", "https://api.pegasusthreesixty.com/v1/companies?limit=50&sort=-value_usd", nil)
req.Header.Set("X-API-Key", os.Getenv("SPEARHEAD_API_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()Response example200 OK
{
"meta": { ... },
"companies": [...],
"page": { "limit": 50, "next_cursor": "eyJvZmZzZXQiOjF9", "has_more": true }
}GET /v1/companies/{slug}Research+
Fetch one company profile and its latest mark.
Request - curlGET /v1/companies/{slug}
curl "https://api.pegasusthreesixty.com/v1/companies/coreweave" \
-H "X-API-Key: $SPEARHEAD_API_KEY"Request - PythonGET /v1/companies/{slug}
import os, requests
resp = requests.get(
"https://api.pegasusthreesixty.com/v1/companies/coreweave",
headers={"X-API-Key": os.environ["SPEARHEAD_API_KEY"]},
timeout=10,
)
resp.raise_for_status()
body = resp.json()
assert body["meta"]["data_mode"] in ("illustrative", "live")
print(body["slug"] if "slug" in body else "ok")Request - JavaScriptGET /v1/companies/{slug}
const resp = await fetch("https://api.pegasusthreesixty.com/v1/companies/coreweave", {
headers: { "X-API-Key": process.env.SPEARHEAD_API_KEY },
});
if (!resp.ok) throw new Error(`${resp.status} ${await resp.text()}`);
const body = await resp.json();
console.log(body.meta.data_mode);Request - GoGET /v1/companies/{slug}
req, _ := http.NewRequest("GET", "https://api.pegasusthreesixty.com/v1/companies/coreweave", nil)
req.Header.Set("X-API-Key", os.Getenv("SPEARHEAD_API_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()Response example200 OK
{
"meta": { ... },
"slug": "coreweave",
"name": "CoreWeave",
"latest_mark": { ... },
"observations": [ ... ]
}GET /v1/companies/{slug}/marksResearch (80) / Pro+ (80 and 95)
Historic marks with 80% band, optional 95% band.
Parameters: coverage = 80 | 95
Request - curlGET /v1/companies/{slug}/marks
curl "https://api.pegasusthreesixty.com/v1/companies/coreweave/marks?coverage=80" \
-H "X-API-Key: $SPEARHEAD_API_KEY"Request - PythonGET /v1/companies/{slug}/marks
import os, requests
resp = requests.get(
"https://api.pegasusthreesixty.com/v1/companies/coreweave/marks?coverage=80",
headers={"X-API-Key": os.environ["SPEARHEAD_API_KEY"]},
timeout=10,
)
resp.raise_for_status()
body = resp.json()
assert body["meta"]["data_mode"] in ("illustrative", "live")
print(body["slug"] if "slug" in body else "ok")Request - JavaScriptGET /v1/companies/{slug}/marks
const resp = await fetch("https://api.pegasusthreesixty.com/v1/companies/coreweave/marks?coverage=80", {
headers: { "X-API-Key": process.env.SPEARHEAD_API_KEY },
});
if (!resp.ok) throw new Error(`${resp.status} ${await resp.text()}`);
const body = await resp.json();
console.log(body.meta.data_mode);Request - GoGET /v1/companies/{slug}/marks
req, _ := http.NewRequest("GET", "https://api.pegasusthreesixty.com/v1/companies/coreweave/marks?coverage=80", nil)
req.Header.Set("X-API-Key", os.Getenv("SPEARHEAD_API_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()Response example200 OK
{
"meta": { ... },
"slug": "coreweave",
"coverage": 80,
"series": [
{ "date": "2025-01-15", "mark_usd": 20100000000, "lower_usd": 9900000000, "upper_usd": 41000000000 }
],
"events": [ ... ]
}GET /v1/companies/{slug}/eventsPro+
Append-only event history for this company.
Request - curlGET /v1/companies/{slug}/events
curl "https://api.pegasusthreesixty.com/v1/companies/coreweave/events" \
-H "X-API-Key: $SPEARHEAD_API_KEY"Request - PythonGET /v1/companies/{slug}/events
import os, requests
resp = requests.get(
"https://api.pegasusthreesixty.com/v1/companies/coreweave/events",
headers={"X-API-Key": os.environ["SPEARHEAD_API_KEY"]},
timeout=10,
)
resp.raise_for_status()
body = resp.json()
assert body["meta"]["data_mode"] in ("illustrative", "live")
print(body["slug"] if "slug" in body else "ok")Request - JavaScriptGET /v1/companies/{slug}/events
const resp = await fetch("https://api.pegasusthreesixty.com/v1/companies/coreweave/events", {
headers: { "X-API-Key": process.env.SPEARHEAD_API_KEY },
});
if (!resp.ok) throw new Error(`${resp.status} ${await resp.text()}`);
const body = await resp.json();
console.log(body.meta.data_mode);Request - GoGET /v1/companies/{slug}/events
req, _ := http.NewRequest("GET", "https://api.pegasusthreesixty.com/v1/companies/coreweave/events", nil)
req.Header.Set("X-API-Key", os.Getenv("SPEARHEAD_API_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()Response example200 OK
{
"meta": { ... },
"slug": "coreweave",
"events": [ { "occurred_on": "2025-01-15", ... } ]
}GET /v1/companies/{slug}/resolutionEnterprise
Audit bundle with signature for enterprise attestations.
Request - curlGET /v1/companies/{slug}/resolution
curl "https://api.pegasusthreesixty.com/v1/companies/coreweave/resolution" \
-H "X-API-Key: $SPEARHEAD_API_KEY"Request - PythonGET /v1/companies/{slug}/resolution
import os, requests
resp = requests.get(
"https://api.pegasusthreesixty.com/v1/companies/coreweave/resolution",
headers={"X-API-Key": os.environ["SPEARHEAD_API_KEY"]},
timeout=10,
)
resp.raise_for_status()
body = resp.json()
assert body["meta"]["data_mode"] in ("illustrative", "live")
print(body["slug"] if "slug" in body else "ok")Request - JavaScriptGET /v1/companies/{slug}/resolution
const resp = await fetch("https://api.pegasusthreesixty.com/v1/companies/coreweave/resolution", {
headers: { "X-API-Key": process.env.SPEARHEAD_API_KEY },
});
if (!resp.ok) throw new Error(`${resp.status} ${await resp.text()}`);
const body = await resp.json();
console.log(body.meta.data_mode);Request - GoGET /v1/companies/{slug}/resolution
req, _ := http.NewRequest("GET", "https://api.pegasusthreesixty.com/v1/companies/coreweave/resolution", nil)
req.Header.Set("X-API-Key", os.Getenv("SPEARHEAD_API_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()Response example200 OK
{
"slug": "coreweave",
"value_usd": 22062735430,
"band_80": { "lower": 10903281498, "upper": 44643834494 },
"band_95": { "lower": 7476958887, "upper": 65101908681 },
"signature": "9f...a08"
}GET /v1/usageResearch+
Current key context and rate-limit state.
Request - curlGET /v1/usage
curl "https://api.pegasusthreesixty.com/v1/usage" \
-H "X-API-Key: $SPEARHEAD_API_KEY"Request - PythonGET /v1/usage
import os, requests
resp = requests.get(
"https://api.pegasusthreesixty.com/v1/usage",
headers={"X-API-Key": os.environ["SPEARHEAD_API_KEY"]},
timeout=10,
)
resp.raise_for_status()
body = resp.json()
assert body["meta"]["data_mode"] in ("illustrative", "live")
print(body["slug"] if "slug" in body else "ok")Request - JavaScriptGET /v1/usage
const resp = await fetch("https://api.pegasusthreesixty.com/v1/usage", {
headers: { "X-API-Key": process.env.SPEARHEAD_API_KEY },
});
if (!resp.ok) throw new Error(`${resp.status} ${await resp.text()}`);
const body = await resp.json();
console.log(body.meta.data_mode);Request - GoGET /v1/usage
req, _ := http.NewRequest("GET", "https://api.pegasusthreesixty.com/v1/usage", nil)
req.Header.Set("X-API-Key", os.Getenv("SPEARHEAD_API_KEY"))
resp, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()Response example200 OK
{
"tier": "free",
"rate_per_min": 60,
"limits": { ... }
}06 / Meta
Response envelope
The response envelope is included on every endpoint for safe downstream checks.
| Field | Type | Description |
|---|---|---|
| data_mode | string | illustrative or live mode flag. |
| provenance | string | backtest or live source tag. |
| methodology_version | string | The methodology version that produced the payload. |
| dataset_version | string | Version of the curated source dataset. |
| as_of | date | Snapshot date used to generate this response. |
| disclaimer | string | Legal / compliance statement for reuse. |
07 / Pagination
Pagination and filters
Use cursor pagination for /v1/companies and keep filters additive.
| Param | Type | Description |
|---|---|---|
| limit | int, 1-200 | Default 50. |
| cursor | string | Opaque cursor from previous response. |
| sector | string | Exact sector match. |
| status | private | ipo_completed | Lifecycle filter. |
| sort | string | One of slug, name, value_usd, delta_30d_pct. Prefix - for descending. |
On next page, pass next_cursor back as cursor. Cached variants are keyed by query string and can be used with ETag.
08 /
Rate limits and 429
Rate limits are tier-based: Research 60 req/min, Pro 600 req/min, Business 3000 req/min, Enterprise 6000 req/min.
| Header | Example | Meaning |
|---|---|---|
X-RateLimit-Limit | 60 | Request budget per minute. |
X-RateLimit-Remaining | 57 | Remaining budget in current window. |
X-RateLimit-Reset | 1718000000 | Window reset epoch. |
Retry-After | 12 | Retry delay after 429. |
Backoff on 429 and retry after the provided seconds.
09 /
Errors
Errors use RFC 9457 application/problem+json. The code field is the integration enum.
| code | Status | Meaning | Cause |
|---|---|---|---|
| missing_api_key | 401 | Unauthorized | No X-API-Key header. |
| invalid_api_key | 401 | Unauthorized | Key is unknown, revoked, or not active. |
| tier_forbidden | 403 | Forbidden | Key tier does not include the requested endpoint. |
| not_found | 404 | Not Found | Unknown resource (for example slug). |
| invalid_coverage | 422 | Unprocessable | coverage is not 80 or 95. |
| invalid_sort | 422 | Unprocessable | Sort parameter is outside the whitelist. |
| bad_cursor | 422 | Unprocessable | Invalid cursor string for pagination. |
| rate_limited | 429 | Too Many Requests | Rate limit exceeded; retry after reset. |
10 /
Compliance and reliability notes
Illustrative / backtest by design
Payloads are labeled clearly with data_mode and provenance. If/when live marks ship, clients can detect that by those values.
Signed records (Enterprise)
Enterprise users can request signed resolution data that includes a cryptographic signature and immutable versioned identifiers for downstream audit systems.
Illustrative / backtest - not live marks. Indicative valuations, not transactable prices. Underlying assets are illiquid; inputs are limited to publicly reported events with source attribution. Pegasus Three Sixty and SpearHead are an information-only valuation product, do not hold client balances, and do not provide investment recommendations.