NetOrca SDK

The official Python SDK for the NetOrca API. Build automation pipelines, manage services, and integrate NetOrca into your CI/CD workflows with a clean, fully typed Python interface.

Installation

pip install netorca-sdk

Requirements: Python 3.8+

Client Initialisation

from netorca_sdk import NetOrcaClient

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

The context parameter controls which point-of-view the client operates from:

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

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

Available Resources

client.services

The definitions published in the NetOrca catalogue — what consumers can order. Each service has a name, JSON Schema, and lifecycle state.

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

client.service_items

A running instance of a service — what a consumer has requested and what the service owner delivers.

item = client.service_items.get(123)
print(item.name, item.runtime_state)

client.deployed_items

Records the provisioning output of a fulfilled change instance — connection strings, hostnames, credentials, or any structured data the consumer needs.

item = client.deployed_items.create({
    "service_item": 123,
    "change_instance": 456,
    "data": {"host": "db-prod-01.internal", "port": 5432}
})
print(item.id)

client.change_instances

A lifecycle event on a service item — a create, modify, or delete request. Automation pipelines watch these, process them, and update the state.

for ci in client.change_instances.list(state="PENDING"):
    print(ci.id, ci.change_type)

client.change_instances.update(ci.id, {"state": "COMPLETED"})

client.service_configs

A snapshot of a service's configuration at a specific version, recorded whenever it's provisioned or modified.

config = client.service_configs.create({
    "service": 45,
    "config": {"engine": "postgres", "size": "medium"}
})
print(config.id, config.version)

client.charges

Billing records attached to service items — either a one-time cost per change or a recurring monthly cost. Read-only.

for charge in client.charges.list():
    print(charge.charge_type, charge.total_charge)

client.applications

A named grouping that belongs to a consumer team; every service item belongs to one. Managed automatically by the platform, so it's read-only.

for app in client.applications.list():
    print(app.name, app.owner_name)

client.submissions

Direct access to submission records — each one is a payload a consumer team sent declaring the state of their applications. Immutable once created.

submission = client.submissions.submit({
    "team_name": {
        "metadata": {"team_email": "team@example.com"},
        "my-application": {"services": {"DATABASE": {"engine": "postgres"}}}
    }
})
print(submission.id, submission.status)

client.healthchecks

Verifies the availability of a service item by making an HTTP request to a configured URL. Results are stored and can be triggered on demand.

result = client.healthchecks.trigger_service_item(service_item_id=123)
print(result)

client.webhooks

Registers a URL for NetOrca to POST to whenever a change instance reaches a configured state.

webhook = client.webhooks.create({
    "target_url": "https://your-service.example.com/netorca/events",
    "service": 45,
    "change_instance_state": "PENDING"
})

client.ai_processors

Defines the prompts NetOrca uses to automate service operations — linked to a service, an LLM model, and an action type (config, verify, execution, etc).

processor = client.ai_processors.create({
    "name": "database-service_config",
    "service": 45,
    "llm_model": 1,
    "action_type": "config",
    "prompt": "Given the consumer request, generate a valid database configuration...",
    "active": True
})

client.ai_documents

Context files attached to a service that an AI processor can retrieve and query when generating a configuration — architecture notes, runbooks, policies.

doc = client.ai_documents.create_for_service(
    service_id=45,
    data={"filename": "runbook.md", "raw_content": "# Runbook\n..."}
)

client.pack_profiles

The configuration record that ties a service's AI pack together — linking processors, validators, and documents into a resolved configuration.

profile = client.pack_profiles.create_for_service(
    service_id=45,
    data={"pack_enabled": True, "top_k": 5}
)

client.pack

Actions for triggering a Pack pipeline stage or retriggering a service or service item's pipeline from CONFIG:

client.pack.trigger(object_id=389, action_type="config")
client.pack.retrigger(object_id=389, serviceowner_comment="The deployment failed; use VLAN 210")

client.messages

Create and delete service-owner messages displayed to eligible consumers.

message = client.messages.create({
    "description": "Scheduled maintenance",
    "expiry_date": "2026-09-30T12:00:00.000Z",
    "scopes": [],
})
client.messages.delete(message.id)

client.llm_models

Language model connections registered in NetOrca — register a model once with its provider credentials, then reuse it across processors and validators.

model = client.llm_models.create({
    "name": "gpt-4o",
    "provider": "openai",
    "model_name": "gpt-4o",
    "api_key": "sk-...",
    "active": True
})

Full Documentation

docs.netorca.io/sdk-guide/introduction

License

MIT License