Skip to content

SDKs

The subsidia-sdk TypeScript client for the platform APIs, and how to use the official OpenAI and Anthropic SDKs, or plain fetch, for everything else.

There is no single Subsidia client for everything, and that is deliberate. The part of the API that most developers use, the Gateway, is OpenAI and Anthropic compatible, so the official OpenAI and Anthropic SDKs are the SDKs for it, in every language they support. A small TypeScript client, subsidia-sdk, covers the platform APIs (knowledge, agents, conversations, completions, webhooks). Everything else is plain HTTP.

You want toUseLanguage
Call a model, stream, use toolsThe official OpenAI or Anthropic SDK pointed at the GatewayAny language those SDKs support
Upload documents, query Cortex, read facts and healthsubsidia-sdk, or fetch / requestsTypeScript, or any HTTP client
Manage agents, memory, conversations, webhookssubsidia-sdk, or HTTPTypeScript, or any HTTP client
Fetch and verify proof certificates, run the Vérificateur, read the RegistreHTTP (not in subsidia-sdk)Any

Gateway: the OpenAI and Anthropic SDKs

Change the base URL and the key, keep everything else. To read the proof id, use the SDK's raw-response helper (withResponse() in TypeScript, with_raw_response in Python) and take the x-pulse-proof header. More on streaming, tools and Claude Code in Gateway.

import OpenAI from 'openai'
const client = new OpenAI({
baseURL: 'https://api.subsidia.protypa.fr/v1',
apiKey: process.env.SUBSIDIA_API_KEY, // sk_live_...
})
const { data, response } = await client.chat.completions
.create({ model: 'pulse-auto', messages: [{ role: 'user', content: 'Hello' }] })
.withResponse()
console.log(data.choices[0].message.content, response.headers.get('x-pulse-proof'))

The TypeScript client: subsidia-sdk

subsidia-sdk is a thin, zero-dependency TypeScript client built on the global fetch (Node 18 or later, Deno, Bun, modern browsers). It lives in the sdk/ folder of the Subsidia repository, version 0.1.0, and is installed with npm install subsidia-sdk. If your registry does not resolve it yet, build it from the sdk/ folder (npm install && npm run build) and npm link it. It sends the key in the x-api-key header.

Configure and use
import { SubsidiaSDK, SubsidiaSDKError } from 'subsidia-sdk'
const subsidia = new SubsidiaSDK({
apiKey: process.env.SUBSIDIA_API_KEY!, // required
// baseUrl: 'https://api.subsidia.protypa.fr', // default; override for an on-premise host
})
// Ingest text, wait until it is ready, then query it
const { id } = await subsidia.knowledge.ingest({
name: 'Lease summary',
content: 'The tenant may terminate the lease with six months written notice.',
})
let status = 'processing'
while (status !== 'ready' && status !== 'failed') {
await new Promise((r) => setTimeout(r, 3000))
status = (await subsidia.knowledge.getSource(id)).source.status
}
const { matches, trace } = await subsidia.knowledge.query({ query: 'Notice period to terminate?', topK: 5 })
try {
await subsidia.agents.list()
} catch (err) {
if (err instanceof SubsidiaSDKError) console.error(err.status, err.body)
else throw err
}
NamespaceMethodsRoutes
knowledgeingest, listSources, getSource, deleteSource, query, listFacts, listContradictions, resolveContradiction, health, replayHealth/v1/knowledge-sources*, /v1/knowledge/*. See Knowledge sources, Knowledge query, Knowledge insights.
agents, agents.memorylist, create, update, delete; memory list, create, delete/v1/agents*. See Agents and Agent memory.
conversationslist, create, get, sendMessage, delete/v1/conversations*. See Conversations.
aicomplete, listExtractedData, getExtractedData, deleteExtractedData/v1/ai/*. See Completions.
webhookslist, create, get, update, delete, deliveries, test/v1/webhooks*. See Webhooks.

Errors. Every non-2xx response throws SubsidiaSDKError, with status (the HTTP status) and body (the parsed JSON body, or null). The body keeps the code field, so you can branch on err.body.code exactly as described in Errors. The client does not retry; add a retry policy around 429 and 5xx yourself.

Plain HTTP

The API is ordinary JSON over HTTPS, so a few lines of fetch or requests are enough for any route, and for any language without an SDK. A minimal typed wrapper that works for every route, including the ones the SDK does not cover:

const BASE = 'https://api.subsidia.protypa.fr'
export async function subsidia<T>(method: string, path: string, body?: unknown): Promise<{ data: T; headers: Headers }> {
const res = await fetch(BASE + path, {
method,
headers: {
Authorization: 'Bearer ' + process.env.SUBSIDIA_API_KEY,
...(body ? { 'Content-Type': 'application/json' } : {}),
},
body: body ? JSON.stringify(body) : undefined,
})
if (!res.ok) throw Object.assign(new Error('Subsidia ' + res.status), { status: res.status, body: await res.json().catch(() => null) })
return { data: (await res.json()) as T, headers: res.headers }
}
// e.g. verify a certificate
const { data } = await subsidia<{ valid: boolean }>('GET', '/v1/proofs/' + proofId + '/verify')

OpenAPI

A machine-readable snapshot of the routes is served at https://dev.subsidia.protypa.fr/openapi.json. It is generated from the server and can be fed to a code generator for languages the SDK does not cover. Treat the written pages as the reference for behaviour and error handling, since a schema does not capture those.

Is there a Python or Go SDK?

Not from Subsidia. For the Gateway use the official OpenAI or Anthropic SDK in your language; for the platform APIs use requests or net/http, optionally with a client generated from the OpenAPI snapshot.

Will the OpenAI SDK break on the extra fields in responses?

No. Responses carry an additional pulse block next to the standard fields, and the SDKs ignore fields they do not know. The block holds the proof id, the provider and the number of values masked.

Related