Skip to main content
Think of Clients as your organization and Instances as individual AI agents or deployments within that organization. One Client can have many Instances, each with its own memory store, configuration, and credentials.
Diagram showing a Client containing multiple Instances, each with its own memory store, config, and credentials

​
What is a Client?

A Client is the top-level organizational entity in Synap. It represents your company, team, or application. When you sign up for Synap and create an account, you are creating a Client. Every Client has a unique identifier in the format cli_<hex16> (for example, cli_a3f8b1c2d4e5f678). This identifier is immutable and used throughout the Synap API and SDK to scope operations to your organization.

​
Client fields

FieldTypeDescription
client_idstringUnique identifier. Format: cli_<hex16>. Immutable after creation.
namestringHuman-readable organization name. Used in the Dashboard and audit logs.
websitestringOrganization website URL. Optional, used for identification.
descriptionstringFree-text description of the organization or use case.
contextJSONBArbitrary metadata stored as JSON. Use for internal tagging, billing references, or integration metadata.
statusenumOne of active, inactive, or soft_deleted. Controls whether the Client’s Instances can operate.
created_attimestampWhen the Client was created. Set automatically.
updated_attimestampWhen the Client was last modified. Updated automatically on changes.
When a Client is set to inactive or soft_deleted, all of its Instances are effectively suspended. No ingestion or retrieval operations will succeed until the Client is reactivated.

​
What is an Instance?

An Instance is a deployed Synap memory agent. It is the unit of deployment — each Instance has its own isolated memory store, configuration, credentials, and scope hierarchy. You create Instances under a Client to represent different AI agents, environments (staging vs. production), or use cases. Every Instance has a unique identifier in the format inst_<hex16> (for example, inst_7b2e9a1c3d4f5678).

​
Instance fields

FieldTypeDescription
instance_idstringUnique identifier. Format: inst_<hex16>. Immutable after creation.
client_idstringThe Client this Instance belongs to. Links to the parent organization.
agent_typestringDescribes the type of agent (e.g., support-bot, sales-assistant, personal-ai). Informational.
statusenumOne of provisioning, active, inactive, or suspended. Controls operational state.
parent_instance_idstring | nullOptional. If set, this Instance is a child in a hierarchical Instance tree.
metadataJSONBArbitrary metadata. Use for environment tags, version tracking, or deployment metadata.
created_attimestampWhen the Instance was created.
updated_attimestampWhen the Instance was last modified.

​
Instance lifecycle

Every Instance progresses through a well-defined lifecycle. Understanding these states helps you manage deployments and debug issues.
1

Provisioning

When you create a new Instance (via the SDK, API, or Dashboard), it enters the provisioning state. During provisioning, Synap allocates storage namespaces, generates bootstrap credentials, and applies the initial Memory Architecture Configuration. The Instance is not operational in this state — ingestion and retrieval calls will be rejected.
2

Active

Once provisioning completes, the Instance transitions to active. This is the normal operational state. The Instance accepts ingestion requests, processes memories through the pipeline, and serves retrieval queries. All authentication credentials are valid.
3

Inactive

An Instance can be set to inactive manually (via the Dashboard or API) to temporarily pause operations. Memories are preserved but no new ingestion or retrieval is processed. Use this for planned maintenance, cost management, or temporary decommissioning. Reactivating an Instance restores full functionality.
4

Suspended

A suspended Instance has been forcibly disabled, typically due to policy violations, billing issues, or administrative action. Unlike inactive, suspension can only be lifted by an administrator. All operations are blocked.
State diagram showing Instance lifecycle: Provisioning to Active, Active to Inactive or Suspended, Inactive back to Active

​
What each Instance owns

Each Instance is a fully isolated environment. When you create an Instance, Synap provisions the following resources exclusively for it:

Bootstrap Key

A unique secrets.token_urlsafe(32) key issued during provisioning. Used for initial SDK authentication before certificate-based auth is established. The SHA-256 hash is stored in the database; the raw key is backed up in KMS.

Credentials

Dual authentication credentials: an API key for REST requests and an mTLS certificate for gRPC streaming. Certificates have a 7-day TTL with a 48-hour grace period for rotation.

Memory Architecture Config

A versioned YAML configuration (MACA) that controls storage, ingestion, and retrieval behavior. Each Instance has its own config with an independent approval workflow. Synap generates the initial MACA from the Use-Case Markdown file you upload at instance creation — the more detail you provide there, the better the starting configuration. See Memory Architecture Configuration and Use-Case Markdown.

Memory Store

Isolated vector and graph storage namespaces. Memories stored in one Instance are never accessible from another Instance unless explicitly shared through scope configuration.

Scoped Memory Boundaries

Each Instance defines its own scope hierarchy (User, Customer, Client, World). Memory isolation boundaries are enforced at the storage layer. See Memory Scopes.

Analytics & Audit Trail

Per-Instance metrics for ingestion throughput, retrieval latency, memory counts, and pipeline health. All operations are audit-logged with timestamps and actor identity.

​
Hierarchical Instances

Instances can be organized in a parent-child hierarchy by setting the parent_instance_id field. This is useful when you need to model complex deployment topologies.

​
When to use hierarchical Instances

  • Multi-environment deployments: A parent Instance for production with child Instances for staging and development, sharing common configuration patterns
  • Multi-tenant applications: A parent Instance per major customer segment, with child Instances for individual tenants that inherit baseline configuration
  • Agent teams: A parent Instance for a team of AI agents where child Instances represent individual specialized agents that share organizational knowledge
# Create a parent Instance
parent = await client.instances.create(
    agent_type="support-team",
    metadata={"environment": "production", "team": "customer-support"}
)

# Create a child Instance under the parent
child = await client.instances.create(
    agent_type="billing-specialist",
    parent_instance_id=parent.instance_id,
    metadata={"environment": "production", "specialization": "billing"}
)
Hierarchical Instances are an organizational tool. Memory isolation is still enforced per-Instance. If you need child Instances to access parent memories, configure shared scoping at the Client level.

​
Managing Clients and Instances

You can create and manage Clients and Instances through three interfaces: 
from synap import Synap

sdk = Synap(api_key="your_api_key")

# List all instances for your client
instances = await sdk.instances.list()

# Get a specific instance
instance = await sdk.instances.get(instance_id="inst_7b2e9a1c3d4f5678")

# Update instance metadata
await sdk.instances.update(
    instance_id="inst_7b2e9a1c3d4f5678",
    metadata={"environment": "production", "version": "2.1.0"}
)

​
Next steps

Memories & Context

Learn how data flows through Synap from ingestion to retrieval.

Memory Scopes

Understand how memory isolation works across users, customers, and organizations.

Authentication

Deep dive into Synap’s zero-trust auth model with API keys and mTLS certificates.

Memory Architecture

Configure how your Instance stores, processes, and retrieves memory.