TypeScript SDK
@ozma_app/sdk client methods for control plane and gateway.
View as Markdown →npm install @ozma_app/sdk
npm: published v0.1.0 (2026-07-07). In-repo version is 0.2.0+ with additional methods — pin to published release for stability or build from monorepo for latest.
Quick start
import { OzmaClient } from "@ozma_app/sdk";
const client = new OzmaClient({
baseUrl: "https://api.ozma.app",
apiKey: process.env.OZMA_API_KEY,
sessionToken: process.env.OZMA_SESSION_TOKEN, // optional; wins over apiKey on control plane
gatewayUrl: "https://gateway.ozma.app", // optional; auto-derived from baseUrl
});
const { data } = await client.search({ q: "weather", sort: "relevance" });
OzmaClientOptions
| Field | Description |
|---|---|
baseUrl |
Control plane (https://api.ozma.app) |
apiKey |
Optional ozma_live_* |
sessionToken |
Optional session — preferred over apiKey for control-plane auth |
gatewayUrl |
Gateway base; defaults to baseUrl with api. → gateway. rewrite |
timeoutMs |
Request timeout (default 30_000) |
Types
SearchSort: ozma_score | price | relevance | new | calls | gmv | reliability | value | momentum
All control-plane methods return Promise<ApiResponse<T>> (Ozma envelope).
Method table
| Method | HTTP | Description |
|---|---|---|
health() |
GET /health |
Service status |
register() |
POST /v1/register |
Auto-register → key, 0 credits |
getMe() |
GET /v1/me |
Org + credits |
listProviders(opts?) |
GET /v1/providers |
Provider directory |
getProviderProfile(slug) |
GET /v1/providers/:slug |
Public profile |
getMyProfile() |
GET /v1/me/profile |
Own profile |
updateMyProfile(patch) |
PATCH /v1/me/profile |
Update profile |
verifyEmail({ token }) |
POST /v1/auth/verify-email |
Email verify |
search({ q?, category?, sort?, limit?, offset? }) |
GET /v1/search |
Catalog search |
categories() |
GET /v1/categories |
Categories |
getApi(slug) |
GET /v1/apis/:slug |
Listing detail |
getSchema(slug) |
GET /v1/apis/:slug/schema |
Schemas |
getEndpoints(slug) |
GET /v1/apis/:slug/endpoints |
Endpoint rows |
getApiStats(slug, window?) |
GET /v1/apis/:slug/stats |
Stats rollup |
getApiHistory(slug, limit?) |
GET /v1/apis/:slug/history |
Score history |
getApiRanks(slug) |
GET /v1/apis/:slug/ranks |
Board ranks |
getLeaderboard(board, category?) |
GET /v1/leaderboards/:board |
Leaderboard |
getMarketOverview() |
GET /v1/market/overview |
Market totals |
getMarketActivity({ limit? }) |
GET /v1/market/activity |
Activity feed (auth) |
createKey({ name, scopes?, budget_cents? }) |
POST /v1/keys |
Mint key |
listKeys() |
GET /v1/keys |
List keys |
revokeKey(id) |
DELETE /v1/keys/:id |
Revoke |
patchKey(id, caps) |
PATCH /v1/keys/:id |
Budget / daily cap / per-call max |
getUsage({ from?, to? }) |
GET /v1/usage |
Usage |
getBillingPacks() |
GET /v1/billing/packs |
Packs |
getBalance() |
GET /v1/billing/balance |
Balance |
createCheckout(opts) |
POST /v1/billing/checkout |
Checkout URL |
createSetupIntent() |
POST /v1/billing/setup-intent |
SetupIntent |
createPortalSession() |
POST /v1/billing/portal |
Portal URL |
configureAutoReload(opts) |
POST /v1/billing/auto-reload |
Auto-reload |
proxyCall(apiSlug, path, method, body?) |
Gateway ALL /v1/proxy/… |
Billed proxy call |
getApiTerms(slug) |
GET /v1/apis/:slug/terms |
Provider terms |
acceptApiTerms(slug, { documentId, contentHash }) |
POST …/terms/accept |
Accept terms (session) |
providerCreateApi(body) |
POST /v1/provider/apis |
Create draft |
providerListApis() |
GET /v1/provider/apis |
List APIs |
providerVerify(apiId) |
POST …/verify |
Smoke test |
providerPublish(apiId, { acceptTerms, skipVerify? }) |
POST …/publish |
Publish — acceptTerms: true required |
providerUnpublish(apiId) |
POST …/unpublish |
Unpublish |
providerUpdatePricing(apiId, { endpoints }) |
PATCH …/pricing |
Pricing |
providerAnalytics() |
GET /v1/provider/analytics |
Analytics |
providerConnectOnboard() |
POST …/connect/onboard |
Connect URL |
providerCreateDocument(body) |
POST /v1/provider/documents |
Draft document |
providerListDocuments(opts?) |
GET /v1/provider/documents |
List documents |
providerActivateDocument(id, body?) |
POST …/activate |
Activate document |
proxyCall notes
- Uses
apiKeyonly (notsessionToken). - Pass explicit
gatewayUrlwhenbaseUrlis localhost. - Returns full Ozma envelope including
meta.cost_centsand billing fields. - Does not expose idempotency key options — set
Idempotency-Keyheader manually if needed. - 428 when required provider terms not accepted.
Scopes
Anonymous register keys: consumer scopes only. Email-verified keys add billing:write + provider:write. See Authentication.