SDKs

The SDKs are thin wrappers over the HTTP API: one method per endpoint, named after the path, with the API's own field names (snake_case). They add retries, idempotency keys on POSTs, typed errors and webhook verification. Anything you can do with an SDK you can do with curl; see the reference.

The command line, aos, is a separate package; see the CLI.

#Configure

All three read the same two environment variables, so no host or key sits in code. AOS_API_BASE includes /api/v1; there is no default host.

export AOS_API_BASE="https://adv.heliosynctech.com/api/v1"
export AOS_KEY="aos_test_paste_your_key_here"

#Make a call

import { AdvocateOS } from "@advocate-os/sdk";

const aos = new AdvocateOS(); // reads AOS_KEY and AOS_API_BASE
const c = await aos.cases.get("SBXX010000012026");
console.log(c.status, c.next_hearing_date);
console.log(c.lastResponse.requestId, c.lastResponse.creditsCharged, c.lastResponse.mode);

from advocate_os import AdvocateOS

aos = AdvocateOS()  # reads AOS_KEY and AOS_API_BASE
case = aos.cases.get("SBXX010000012026")
print(case["status"], case["next_hearing_date"])
print(case.last_response.request_id, case.last_response.credits_charged, case.last_response.mode)

<?php
require 'vendor/autoload.php';

$aos = new \AdvocateOS\AdvocateOS(); // reads AOS_KEY and AOS_API_BASE
$case = $aos->cases->get('SBXX010000012026');
echo $case['status'], ' ', $case['next_hearing_date'], "\n";
echo $aos->lastResponse->requestId, ' ', $aos->lastResponse->creditsCharged, "\n";

#What the methods are

One resource per area, with the API's own parameter names. In TypeScript:

aos.cases.search({ number: "3964/2026" });  aos.cases.get(cnr, { fresh: true });  aos.cases.orders(cnr);
aos.orders.get(id);  aos.orders.pdf(id);  aos.orders.summary(id);
aos.causeLists.list({ court, date, q });  aos.causeLists.match({ cnrs, date });
aos.judgments.search({ q, court, from, to });  aos.judgments.get(id);  aos.judgments.citator(id);
aos.reports.create({ type: "litigation_check", subject });  aos.reports.get(id);  aos.reports.wait(id);
aos.watches.create({ kind: "case", cnr });  aos.webhookEndpoints.create({ url });  aos.events.list({ after });
aos.ocr.create({ file });  aos.records.read(body);  aos.translate.create({ text, to });
aos.research.answer({ question });  aos.drafts.create({ blueprint, facts });
aos.workspace.matters();  aos.sandbox.emitEvent({ type });  aos.account.get();  aos.usage.get({ group: "endpoint" });

Python and PHP have the same resources (cause_lists and causeLists, and so on). The full list is in each package's README. The SDKs may not wrap every endpoint yet: GET /jobs/{id} (intelligence jobs) and GET /drafts/blueprints may arrive in a later release. Until then use the escape hatch, aos.request(method, path, options), which sends your key, version and idempotency key for you:

const job = await aos.request("GET", `/jobs/${jobId}`);

#What the SDKs do for you

• Errors become exceptions. Every non-2xx response is thrown as an AdvocateOSError (AdvocateOSException in PHP) with type, code, param, docUrl and requestId (doc_url and request_id in Python). In PHP the machine code is errorCode, because code is the exception's own integer. Branch on the code. Read the doc URL before you retry. See errors.
• Retries. A 429 or 503 is retried twice by default, with backoff, honouring RateLimit-Reset. Change it with the retries option.
• Idempotency. Every POST gets an Idempotency-Key, and a retry reuses it, so a retried call is never billed twice. Pass your own key to retry across restarts. See idempotency.
• Pagination. A list is a page you can iterate; it fetches the next page when you reach the end, and each page is a billed call, so set a limit and stop early. See pagination.
• Version. The SDK sends AOS-Version for the release it was built against. See versioning.
• Sandbox date. Set the sandbox date option to send AOS-Sandbox-Date on every call, with a test key.
• Response details. The last response carries the request id, AOS-Credits-Charged, the mode and the rate-limit headers.

#Verify a webhook

Each SDK has a webhooks.verify helper that checks AOS-Signature against the raw body and returns the event. It throws an error for a bad signature or an old timestamp. See webhooks for what is checked.

import { webhooks } from "@advocate-os/sdk";

const event = webhooks.verify(rawBody, req.header("AOS-Signature") ?? "", process.env.AOS_WEBHOOK_SECRET!);

from advocate_os import webhooks

event = webhooks.verify(raw_body, request.headers["AOS-Signature"], WEBHOOK_SECRET)

<?php
$event = \AdvocateOS\Webhook::verify($rawBody, $_SERVER['HTTP_AOS_SIGNATURE'] ?? '', getenv('AOS_WEBHOOK_SECRET'));

#For AI coding tools

Each package ships an AGENTS.md that tells a coding agent how to use it. See build with AI.