Documentation
Documentation

Overview

Spore docs

Start here

Getting startedInstall the CLIAuthentication and keys

Build

Search and filtersSegments and the loopEnrichment lifecycle

Recipes

Recipe: search to a live SegmentRecipe: enrich without a segmentRecipe: land your own research

Connect

Events

Account

Credits and billing

Reference

Conventions
API reference
Export the organization's Operation calls POSTPage the organization's Operation calls GETExport the organization's recorded acts POSTPage the organization's recorded acts GETCancel an enrichment launch POSTRead a vocabulary: tools, filters, knowledge, or NACE GETPublish a staged Commons Generation POSTRestore the retained previous Commons Generation POSTPage the organization's Companies GETCorrect a Company's Core under Spore-If-Match PATCHDelete a Company DELETERead everything you know about one Company GETRead Legal entity data for Companies you hold POSTFind Legal entities in the Commons POSTFold one Company into another POSTMint Companies from your own data, or attach rows to Companies you hold POSTPromote a declared current Fact into Company Core POSTRead one Company GETMeasure requested fields over a set of Companies POSTRun a native enrichment POSTPoll an enrichment GETFollow the organization's durable events stream GETPage a Job's frozen target list GETCreate an API key and reveal its secret once POSTRevoke an organization API key POSTList per-item enrichment outcomes GETDeclare a namespace and its fields before recording into them POSTDelete a declaration while nothing stands on it DELETERead your Catalog GETRecord what you observed about a Company or concluded about a Segment POSTUnlock every Legal entity a search matched POSTSearch the Commons: count, analytics, and a minted sample POSTPage a Segment's members, with the exact count GETName a live filter over your Companies POSTDelete a Segment DELETERead what you have concluded about one Segment GETRename a Segment, or change what it means, under Spore-If-Match PATCHRead a Segment's name and filter GETPage the organization's Segments GETPage the organization's credit ledger GETRead the balance and this key's spend bounds GET
API reference

Search the Commons: count, analytics, and a minted sample

Runs a filter AST against the live Commons and answers with the population's count, its full analytics, and a sample of matching Legal entities minted as Companies of this organization — verified and unlocked from birth, with Core pre-filled from the registry. The charge is `max(5, newly unlocked)`: the floor pays for the count and analytics, and every Legal entity this organization has not unlocked before costs one credit, once, forever. A Company it already holds is unlocked in place rather than duplicated. An identical request replayed inside the receipt's window returns the original sample for nothing. The quote is the worst case, `max(5, sampleSize)`, computed before anything is read or written; the call is refused whole when it exceeds `maxCredits` or the key's bounds, and the charge never exceeds it. `dryRun` returns the quote without reading the Commons, minting, unlocking, or charging. Unlock the whole population with `POST /api/v1/search/{searchId}/unlock`. Variable price, quoted per request: up to 100 credits per call. Charged max(5, newly unlocked Legal entities); an active receipt replays for 0.

POST
/api/v1/search

Runs a filter AST against the live Commons and answers with the population's count, its full analytics, and a sample of matching Legal entities minted as Companies of this organization — verified and unlocked from birth, with Core pre-filled from the registry. The charge is max(5, newly unlocked): the floor pays for the count and analytics, and every Legal entity this organization has not unlocked before costs one credit, once, forever. A Company it already holds is unlocked in place rather than duplicated. An identical request replayed inside the receipt's window returns the original sample for nothing. The quote is the worst case, max(5, sampleSize), computed before anything is read or written; the call is refused whole when it exceeds maxCredits or the key's bounds, and the charge never exceeds it. dryRun returns the quote without reading the Commons, minting, unlocking, or charging. Unlock the whole population with POST /api/v1/search/{searchId}/unlock.

Variable price, quoted per request: up to 100 credits per call. Charged max(5, newly unlocked Legal entities); an active receipt replays for 0.

Authorization

bearerAuth
AuthorizationBearer <token>

In: header

Header Parameters

Idempotency-Key*string

Required for writes. Reusing this key with the same input replays the original response.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/search" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "filter": null,    "sampleSize": 5,    "maxCredits": 5  }'
{  "dryRun": true,  "quote": 0}

Unlock every Legal entity a search matched POST

Mints every Legal entity the receipt's filter matches as a Company of this organization and unlocks it, at one credit per entity not unlocked before. The quote is computed from the live population before anything is written; the call is refused whole — never partly applied — when it exceeds `maxCredits`, the plan's Company allowance, or the balance, and `dryRun` returns the same quote without minting, unlocking, or charging. Two kinds of match are left alone and never charged, and both are counted in the response: `conflicts`, where an identifier of the entity belongs to a Company that already names a different Legal entity (a merge, not an unlock), and `incomplete`, where the registry record cannot make a Company's Core. A population above 50,000 entities is refused: narrow the filter and search again. The Companies it creates are listed through `GET /api/v1/companies`. Variable price, quoted per request. 1 credit per Legal entity not yet unlocked, once, forever. Already-unlocked entities are free.

Page a Segment's members, with the exact count GET

Evaluates the filter now and returns one page of members newest first under an opaque cursor, plus the exact total of the whole set. Registry predicates are evaluated in the Commons over the Legal entities you have unlocked, so a verified-but-locked Company never appears and membership can never reveal data you have not paid for. Reading your own set is not an acquisition. Free.

filter?|null
sortBy?string
Default"legalName"

Value in

  • "legalName"
  • "countryCode"
  • "registrationDate"
  • "primaryActivityCode"
  • "revenue"
  • "profit"
  • "employees"
sortOrder?string
Default"asc"

Value in

  • "asc"
  • "desc"
sampleSize?integer
Range5 <= value <= 100
Default5
maxCredits*integer
Range0 <= value <= 9007199254740991
dryRun?boolean
Defaultfalse