SDKs

1. Available SDKs

   Both clients are open source, and both wrap the same REST API. Reach for one when you want auth, retries, redaction, and error handling already solved.

   JavaScript / TypeScript Typed client for Node.js 20 and above, published as @phyi/sdk. Returns a result object rather than throwing. View source Python Client for CPython 3.10 and above, published as phylax-sdk. Raises a typed exception hierarchy. View source

2. Install

   JavaScript

   npm install @phyi/sdk

   Python

   pip install phylax-sdk

   The distribution is phylax-sdk and the import is phylax. An unrelated project already holds the name phylax on PyPI, so check what you are installing.

3. Authenticate

   The SDKs require a paid subscription. Anonymous access covers the public catalog and search on the web, and stops there. Every call in this guide needs a Builder plan or above, so create a token in the key manager and expose it as PHYLAX_API_TOKEN. Both clients read that variable, so nothing in your source has to hold the credential.

   A token is required. Constructing a client without one fails immediately rather than at the first request, so a missing secret surfaces at startup instead of halfway through a deploy.

   JavaScript

   import { PhylaxSdk } from '@phyi/sdk';
   
   const phylax = new PhylaxSdk({
     apiToken: process.env.PHYLAX_API_TOKEN,
   });

   Python

   from phylax import Phylax
   
   phylax = Phylax()  # reads PHYLAX_API_TOKEN from the environment

4. Verify an artifact

   Methods are grouped by the resource they act on, so the call reads like the question you are asking.

   JavaScript

   const result = await phylax.artifacts.verify('pkg:npm/express@4.18.2');
   
   if (!result.success) {
     console.error(result.code, result.error);
     process.exit(1);
   }
   
   console.log(result.data.verdict); // 'ALLOW' | 'WARN' | 'BLOCK'

   Python

   result = phylax.artifacts.verify("pkg:npm/express@4.18.2")
   
   print(result["verdict"])  # 'ALLOW' | 'WARN' | 'BLOCK'

   Verify a whole dependency list in one call. One batch request costs a single unit of quota where a loop costs one per artifact, and it avoids paying network latency once per dependency.

   JavaScript

   const result = await phylax.artifacts.verifyMany([
     'pkg:npm/express@4.18.2',
     'pkg:pypi/requests@2.32.3',
   ], { policy: 'prod-runtime-policy' });

   Python

   results = phylax.artifacts.verify_many(
       ["pkg:npm/express@4.18.2", "pkg:pypi/requests@2.32.3"],
       policy="prod-runtime-policy",
   )

5. Handle failure

   The two clients report failure differently, because the idiomatic answer differs by language. TypeScript cannot force you to catch an exception, so the JavaScript client returns a result you have to inspect before reaching the data. Python callers already expect try and except, so the Python client raises.

   JavaScript

   const result = await phylax.policies.evaluate('pkg:npm/express@4.18.2');
   
   if (!result.success) {
     switch (result.code) {
       case 'plan_required':
         return upgradePrompt();
       case 'quota_exceeded':
         return notifyOwner();
       case 'rate_limited':
         return retryLater();
       default:
         throw new Error(result.error);
     }
   }

   result.data is only reachable on the success branch, so the compiler stops you from reading a field off a failed call.

   Python

   from phylax import APIFailure, APIPlanRequired, APIQuotaExceeded
   
   try:
       decision = phylax.policies.evaluate("pkg:npm/express@4.18.2")
   except APIPlanRequired:
       upgrade_prompt()
   except APIQuotaExceeded:
       notify_owner()
   except APIFailure as error:
       log.warning("%s: %s", error.code, error.message)

   Every exception derives from APIFailure, so one handler catches everything while the narrower cases stay available.

   Rate limits and transient faults are retried for you, with Retry-After honoured when present and exponential backoff with full jitter otherwise. Writes are the exception: a POST or DELETE retries only on 408 and 429, never on a 5xx, because the server may have committed the change before failing to respond.

6. Check entitlements before you spend

   Access is gated by plan, by token permission, and by period allowance. Most of the SDK is available on Builder; policy controls start at Marketplace, because a policy is how a team enforces one decision across everyone. Rather than discovering a rejection mid-run, ask first.

   JavaScript

   const entitlements = await phylax.quota.entitlements();
   
   if (!entitlements.success) {
     throw new Error(entitlements.error);
   }
   
   const check = phylax.quota.checkAccess('policies.evaluate', entitlements.data);
   
   if (!check.allowed) {
     throw new Error(check.reasons.join('; '));
   }

   Python

   entitlements = phylax.quota.entitlements()
   check = phylax.quota.check_access("policies.evaluate", entitlements)
   
   if not check.allowed:
       raise SystemExit("; ".join(check.reasons))

   Read entitlements once at startup and cache them. They change when a subscription changes, not between requests. Treat the check as a fast path that avoids a doomed call, and still handle the rejection at the call site, because the server is the authority and a local table can be stale.

7. Resource map

   artifacts verify, verifyMany, get, list, search. Verification and lookup for packages, MCP servers, repositories, and skills.

   attestations list, get, verify. Signed evidence, and the check that confirms a bundle you already hold.

   policies list, get, create, update, delete, evaluate. The rule that turns findings into a verdict.

   repositories list, get, add, remove, verify. Track a source repository, or verify one you do not own.

   webhooks list, get, create, update, delete, plus signature verification for inbound deliveries.

   quota entitlements, checkAccess, and the cost table behind every method.

   Full signatures live with each SDK: TypeScript reference, Python reference.

Treat an unknown verdict as BLOCK

A verdict is ALLOW, WARN, or BLOCK, not a boolean and not a score to threshold. Thresholds belong in policy, where they change without a redeploy. Branch on the verdict you know and fail closed on anything you do not, so a value added in a later API version stops the pipeline rather than passing through it. See Error codes for what is worth retrying.

Related guides

For the endpoints behind these methods, see the REST API. For a terminal workflow, see the Phylax CLI. To verify inbound webhook deliveries, see Webhooks.