SDKs

Archyl provides official SDKs for Node.js and Python. Both are lightweight wrappers around the REST API that handle authentication, serialization, and error handling for you.

Installation

Node.js

npm install @archyl/sdk

Python

pip install archyl-sdk

Quick Start

Node.js

import { ArchylClient } from "@archyl/sdk";

const client = new ArchylClient({
  apiKey: process.env.ARCHYL_API_KEY,
  organizationId: "your-org-id",
});

// List projects
const projects = await client.projects.list();

// Get C4 model
const model = await client.projects.getC4Model("project-id");

// Compute drift score
const drift = await client.governance.computeDrift("project-id");

// Create an ADR
const adr = await client.docs.createADR("project-id", {
  title: "Use PostgreSQL for persistence",
  status: "accepted",
  context: "We need a relational database for transactional data.",
  decision: "Adopt PostgreSQL 16 as the primary datastore.",
  consequences: "Team must learn PostgreSQL-specific features.",
});

Python

from archyl import ArchylClient

client = ArchylClient(
    api_key=os.environ["ARCHYL_API_KEY"],
    organization_id="your-org-id",
)

# List projects
projects = client.projects.list()

# Get C4 model
model = client.projects.get_c4_model("project-id")

# Compute drift score
drift = client.governance.compute_drift("project-id")

# Create an ADR
adr = client.docs.create_adr("project-id",
    title="Use PostgreSQL for persistence",
    status="accepted",
    context="We need a relational database for transactional data.",
    decision="Adopt PostgreSQL 16 as the primary datastore.",
    consequences="Team must learn PostgreSQL-specific features.",
)

API Reference

Projects

C4 Model

Governance

DORA Metrics

Documentation

Error Handling

Both SDKs throw typed errors with the HTTP status code and error details from the API.

Node.js

import { ArchylError } from "@archyl/sdk";

try {
  await client.projects.get("nonexistent-id");
} catch (error) {
  if (error instanceof ArchylError) {
    console.error(error.status); // 404
    console.error(error.code); // "NOT_FOUND"
    console.error(error.message); // "Project not found"
  }
}

Python

from archyl import ArchylError

try:
    client.projects.get("nonexistent-id")
except ArchylError as e:
    print(e.status)   # 404
    print(e.code)     # "NOT_FOUND"
    print(e.message)  # "Project not found"

Common status codes:

Configuration

Custom Base URL

For self-hosted Archyl instances, pass a custom baseUrl:

const client = new ArchylClient({
  apiKey: "your-api-key",
  organizationId: "your-org-id",
  baseUrl: "https://archyl.your-company.com/api/v1",
});

client = ArchylClient(
    api_key="your-api-key",
    organization_id="your-org-id",
    base_url="https://archyl.your-company.com/api/v1",
)

Source Code

Both SDKs are open source:

• github.com/archyl-com/sdk

Next Steps

• API Overview - Full REST API documentation
• Authentication - API key management
• MCP Server - AI assistant integration