Skip to main content

SDK Overview

Terragnos Core provides official SDKs for TypeScript/Node.js, Python, and .NET. These SDKs are generated from the OpenAPI specification and provide type-safe, idiomatic interfaces for interacting with the platform.

Available SDKs​

SDKLanguagePackageInstallation
TypeScript/Node.jsTypeScript, JavaScript@terragnos/sdk-adminnpm install @terragnos/sdk-admin
PythonPython 3.9+terragnos-admin-clientpip install terragnos-admin-client
.NETC# (.NET 8+)Terragnos.AdminSdkdotnet add package Terragnos.AdminSdk

SDK Features​

All SDKs provide:

  • Type-safe APIs – Full TypeScript/Python/.NET type definitions generated from OpenAPI
  • Authentication – Built-in JWT token handling with automatic header injection
  • Error handling – Structured error responses with status codes and messages
  • Request/response models – Strongly-typed DTOs for all operations
  • OpenAPI compliance – Generated from the official OpenAPI spec, always in sync
  • Time-travel support – Built-in asOf parameter support for historical queries
  • Optimistic locking – If-Match header support for concurrent updates
  • Helper methods – High-level methods for common operations (workflow transitions, rule explanations)

When to Use SDKs​

Use SDKs when:

  • Building applications that integrate with Terragnos Core
  • You want type safety and IDE autocomplete
  • You prefer high-level abstractions over raw HTTP
  • You're building scripts or automation tools

Use raw HTTP when:

  • Integrating with tools that don't support SDKs
  • You need fine-grained control over requests
  • You're prototyping quickly
  • SDKs aren't available for your language

Common Patterns​

Authentication​

All SDKs support JWT token authentication:

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

```typescript import { TerragnosAdminClient } from '@terragnos/sdk-admin'; 
const client = new TerragnosAdminClient({
  baseUrl: 'https://core.example.com/v1',
  token: process.env.TERRAGNOS_TOKEN
});
```
 ```python from terragnos_admin_client import TerragnosAdminClient 
client = TerragnosAdminClient(
    base_url="https://core.example.com/v1",
    token="Bearer ..."
)
```
 ```csharp using Terragnos.AdminSdk; 
var client = new TerragnosAdminClient(
    "https://core.example.com/v1",
    token: Environment.GetEnvironmentVariable("TERRAGNOS_TOKEN")
);
```

Error Handling​

SDKs provide structured error handling:

// TypeScript
try {
  const objects = await client.listObjects({ limit: 25 });
} catch (error) {
  if (error.statusCode === 403) {
    // Handle permission error or license limit
  } else if (error.statusCode === 409) {
    // Handle optimistic locking conflict
  } else if (error.statusCode === 429) {
    // Handle rate limit - check Retry-After header
  }
}
# Python
try:
    objects = client.request("/objects", method="GET", query={"limit": 25})
except Exception as e:
    if hasattr(e, 'status_code'):
        if e.status_code == 403:
            # Handle permission error
        elif e.status_code == 429:
            # Handle rate limit
// .NET
try {
    var result = await client.ListObjectsAsync(new Dictionary<string, string?> 
    { 
        ["limit"] = "25" 
    });
} catch (HttpRequestException ex) {
    // Handle HTTP errors
}

SDK Updates​

SDKs are updated with each Terragnos Core release to match the latest API. Always use SDK versions that match your Terragnos Core deployment version.

Next Steps​