Getting started

Mint a key

API keys are organization-scoped and minted from the dashboard:

1. Open Dashboard → Organization → API keys.
2. Press Create API key, name it, choose access and expiry, and set spend bounds for priced scopes.
3. Copy the key. It is shown once and never stored in readable form.

Organization owners and admins can mint and revoke keys. See Authentication and keys for scopes, exact Operation allowlists, and delegation. The Free plan includes API access and 50 credits when you sign up; 500 more when an Owner verifies a payment method (no charge). The Owner verifies one from Dashboard → Organization → Billing, on the Free plan card; see Credits and billing for what counts as verified.

Authenticate

Every request carries the key as a bearer token:

export SPORE_API_KEY=spore_sk_...

curl https://www.spore.ee/api/v1/wallet \
  -H "Authorization: Bearer $SPORE_API_KEY"

GET /api/v1/wallet is free and org-wide: it returns the current balance plus lifetime purchased, granted, and used totals. An agent deciding whether it can afford a batch reads this first.

Discover what you can run

curl https://www.spore.ee/api/v1/catalog?section=tools \
  -H "Authorization: Bearer $SPORE_API_KEY"

GET /api/v1/catalog?section=tools lists every workflow a key can run with its route, base credit cost, JSON Schema for the request body, and an example request that parses against it. It is generated from the same contracts the routes validate with, so a tool listed here cannot have a schema the route rejects. Free and cacheable.

Its sibling GET /api/v1/catalog?section=filters does the same job for search: it is the vocabulary of filterable fields, their operators, and their enum domains.

Your first search

Search takes a filter AST and returns the match count, the full aggregate over every match, and a sample of at most 100 companies:

{
	"filter": {
		"type": "group",
		"logic": "AND",
		"children": [
			{
				"type": "rule",
				"fieldId": "countryCode",
				"operator": "in",
				"value": ["EE"]
			}
		]
	},
	"sortBy": "revenue",
	"sortOrder": "desc",
	"maxCredits": 5
}

curl -X POST https://www.spore.ee/api/v1/search \
  -H "Authorization: Bearer $SPORE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: getting-started-search-1" \
  -d @search.json

The response carries searchResultId, filterHash, count, analytics, sample, newlyUnlocked, alreadyUnlocked, charged, balance, replayed, and expiresAt. The sample is Companies of yours: the search mints each sampled Legal entity and unlocks it. A search charges max(5, newly unlocked Legal entities); repeating the same request identity within 24 hours is free — the identity includes filter, sortBy, sortOrder, and sampleSize, not filterHash alone. charged: 0 and replayed: true say so.

Monitor calls and cost

Open Organization → Audit ledger for the same organization-scoped rows returned by GET /api/v1/audit/calls. The console refreshes every 30 seconds. A key with wallet:read can page calls using cursor and limit, or filter by apiKeyId.

Each authenticated call records its Operation, key, request ID, HTTP status, time, and actual net credit cost. A null status means no response has been recorded yet. Free calls and refusals remain visible. Replays have their own zero-cost rows. Later Job charges, Unlocks, and refunds update the original call, never its quote or replay.

POST /api/v1/audit/calls/export requires export:run and an Idempotency-Key. Choose selected call IDs, a key-filtered query, or the whole Collection; explicitly select from id, operationId, apiKeyId, requestId, status, costCredits, and createdAt. CSV, JSONL, and XLSX use the shared Export contract. Small exports return inline content; larger exports return an artifact receipt. The console uses the same allowlist.

The same page and the same wallet:read scope also serve the organization's recorded acts — Job and Run transitions, exports, balance changes, key policy and limits changes — through GET /api/v1/audit/events. Each row names its actor (a member, an API key, or the platform), its subject, and its time; a revoked or expired key's refused call appears in the calls ledger with that key and status 401.

Narrow that chronology with kind, an exact recorded kind such as key.policy_changed: it is a filter on the same organization-scoped read, not a separate Operation, so it composes with cursor and limit. Every page carries recordedKinds, the vocabulary this deploy records and therefore every value kind accepts, so read the list from the page rather than guessing. A kind this deploy has never recorded is refused with 422 and the message names the vocabulary it knows, so a mistyped kind is never answered with an empty page.

POST /api/v1/audit/events/export requires export:run and an Idempotency-Key. Choose the current kind query or the whole chronology; explicitly select from id, at, kind, actorKind, actorId, actorName, jobId, runId, segmentId, companyId, apiKeyId, exportId, transactionId, credits, balanceAfter, and detail. A field outside that allowlist is refused with 422. Rows are frozen when the export is requested, so a durable artifact carries the chronology you asked for rather than the one it has since grown into. The console offers the same export.

Where to go next