Introduction

The NetOrca SDK is the official Python library for the NetOrca API. It provides a clean, typed interface to manage services, consumers, change instances, AI automation, and more — all from Python or your CI/CD pipeline.

Installation

pip install netorca-sdk

Requirements: Python 3.8+

Client setup

Every interaction starts with a NetOrcaClient. You need your instance URL and an API key.

from netorca_sdk import NetOrcaClient

client = NetOrcaClient(
    fqdn="https://your-instance.netorca.io/v1",
    api_key="YOUR_API_KEY",
)

The client validates your API key immediately on creation. If you need to skip that (for testing or offline use), or disable SSL verification for an internal instance with a self-signed certificate:

# Skip auth check on init
client = NetOrcaClient(
    fqdn="https://your-instance.netorca.io/v1",
    api_key="YOUR_API_KEY",
    verify_auth=False,
)

# Disable SSL verification (e.g. internal instance with self-signed cert)
client = NetOrcaClient(
    fqdn="https://your-instance.netorca.io/v1",
    api_key="YOUR_API_KEY",
    verify_ssl=False,
)

Context

NetOrca has two points of view — service owner (the team that publishes services) and consumer (the team that requests them). Pass context to tell the client which one to use:

client = NetOrcaClient(fqdn="...", api_key="...", context="serviceowner")  # default
client = NetOrcaClient(fqdn="...", api_key="...", context="consumer")

Parameters

Parameter	Type	Default	Description
fqdn	str	required	Base URL of your NetOrca instance
api_key	str	required	Your NetOrca API key
context	str	"serviceowner"	"serviceowner" or "consumer"
verify_ssl	bool	True	Verify SSL certificates on every request
verify_auth	bool	True	Validate the API key on creation

Basic usage

All resources live as properties on the client. Nothing is fetched until you call a method.

# Iterate all services
for service in client.services.list():
    print(service.name, service.state)

# Get one item by ID
item = client.service_items.get(123)
print(item.name, item.runtime_state)

# Filter to a list
pending = client.change_instances.filter(state="PENDING")
for ci in pending:
    print(ci.id, ci.change_type)

Working with results

Every model exposes its fields as properties and can be converted back to a dict:

item = client.service_items.get(123)

item.id                  # int
item.name                # str
item.runtime_state       # str
item.service_name        # str  (resolved from nested object)
item.application_name    # str  (resolved from nested object)
item.created             # datetime
item.modified            # datetime

item.to_dict()           # raw API response as dict
item.refresh()           # re-fetch from API

Resources

Property	Description
client.services	Service catalogue
client.service_items	Service item instances
client.deployed_items	Deployed item records
client.change_instances	Change requests and lifecycle events
client.service_configs	Service configuration snapshots
client.charges	Billing and charge records
client.applications	Consumer applications
client.submissions	Submission records
client.healthchecks	Healthcheck endpoints
client.webhooks	Webhook registrations
client.ai_processors	AI processor definitions
client.ai_documents	AI context documents
client.pack_profiles	Pack profile configurations
client.llm_models	LLM model registrations

Error handling

All SDK exceptions inherit from NetorcaBaseException:

from netorca_sdk.exceptions import (
    NetorcaAuthenticationError,
    NetorcaNotFoundError,
    NetorcaAPIError,
    NetorcaBaseException,
)

try:
    item = client.service_items.get(999)
except NetorcaAuthenticationError:
    print("Invalid API key")
except NetorcaNotFoundError:
    print("Not found")
except NetorcaAPIError as e:
    print(f"API error: {e}")

See Error Handling for the full exception reference.