Skip to content

Lucid SDK Quickstart

Use the Lucid SDK to interact with the Verifier API from Python or TypeScript. The SDK is auto-generated from the OpenAPI spec — every endpoint, model, and parameter is fully typed.

Alpha Access Required

The Lucid SDK is available to alpha participants. Request access to get started.

Python

Install

pip install lucid-sdk

Authenticate

from lucid_sdk import AuthenticatedClient

client = AuthenticatedClient(
    base_url="https://api.us-east-1.lucid.ai",
    token="your-api-key",
)

export LUCID_API_KEY=your-api-key

import os
from lucid_sdk import AuthenticatedClient

client = AuthenticatedClient(
    base_url="https://api.us-east-1.lucid.ai",
    token=os.environ["LUCID_API_KEY"],
)

Use

# List your agents
agents = client.v1_list_agents()
for agent in agents:
    print(f"{agent.name} — {agent.status}")

# Get a passport
passport = client.v1_get_passport(passport_id="psp_abc123")
print(passport.status, passport.issued_at)

# Submit evidence
evidence = client.v1_submit_evidence(
    passport_id="psp_abc123",
    body={"claim": "injection_risk", "value": 0.02},
)

Async

The SDK uses httpx under the hood and supports async natively:

import asyncio
from lucid_sdk import AuthenticatedClient

async def main():
    client = AuthenticatedClient(
        base_url="https://api.us-east-1.lucid.ai",
        token="your-api-key",
    )
    agents = await client.v1_list_agents()
    for agent in agents:
        print(agent.name)

asyncio.run(main())

TypeScript / JavaScript

Install

npm install @lucid/sdk

Authenticate

import { createLucidClient } from "@lucid/sdk";

const client = createLucidClient({
  baseUrl: "https://api.us-east-1.lucid.ai",
  headers: {
    Authorization: "Bearer your-api-key",
  },
});

Use

Every method is fully typed — paths, parameters, request bodies, and responses are all inferred from the OpenAPI spec.

// List agents
const { data: agents, error } = await client.GET("/v1/agents");
if (agents) {
  for (const agent of agents) {
    console.log(agent.name, agent.status);
  }
}

// Get a passport (path params are type-checked)
const { data: passport } = await client.GET("/v1/passports/{passport_id}", {
  params: { path: { passport_id: "psp_abc123" } },
});

// Submit evidence
const { data: evidence } = await client.POST(
  "/v1/passports/{passport_id}/evidence",
  {
    params: { path: { passport_id: "psp_abc123" } },
    body: { claim: "injection_risk", value: 0.02 },
  },
);

Type Imports

You can import the generated types directly for use in your own code:

import type { paths } from "@lucid/sdk";

// Extract a specific response type
type Agent = paths["/v1/agents"]["get"]["responses"]["200"]["content"]["application/json"][number];

function renderAgent(agent: Agent) {
  return `${agent.name} (${agent.status})`;
}

What's Included

Feature Python (lucid-sdk) TypeScript (@lucid/sdk)
Typed models Pydantic v2 dataclasses Zero-runtime TypeScript types
HTTP client httpx (sync + async) openapi-fetch (native fetch)
Auth AuthenticatedClient class Headers option
Error handling Typed exceptions { data, error } pattern
Tree-shakeable N/A Yes

Next Steps