Engramma

Organizations

intermediate

Create, manage, and configure organizations. Invite members, manage roles, and handle API keys.

Create organization

POST/v1/organizations

Create a new organization. The authenticated user becomes the first admin.

namestringrequired

Organization display name. Max 100 characters.

slugstringrequired

URL-friendly identifier. Lowercase, alphanumeric, hyphens only. Must be unique.

201Response
{
  "id": "org_abc123",
  "name": "Acme Engineering",
  "slug": "acme-eng",
  "your_role": "admin",
  "member_count": 1,
  "plan": "free",
  "created_at": "2026-01-15T10:00:00Z"
}
import os
from engramma_cloud import EngrammaClient

client = EngrammaClient(api_key=os.environ["ENGRAMMA_API_KEY"])

org = client.organizations.create(
    name="Acme Engineering",
    slug="acme-eng"
)
print(f"Created: {org.id} ({org.slug})")

List organizations

GET/v1/organizations

List all organizations you belong to.

200Response
{
  "data": [
    {
      "id": "org_abc123",
      "name": "Acme Engineering",
      "slug": "acme-eng",
      "your_role": "admin",
      "member_count": 5,
      "plan": "professional"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}

Get organization

GET/v1/organizations/{org_id}

Retrieve details for a specific organization.

org_idstringrequired

Organization ID (path parameter).

200Response
{
  "id": "org_abc123",
  "name": "Acme Engineering",
  "slug": "acme-eng",
  "your_role": "admin",
  "member_count": 5,
  "plan": "professional",
  "settings": {
    "default_importance": 0.5,
    "auto_consolidation": true
  },
  "created_at": "2026-01-15T10:00:00Z"
}

Update organization

PATCH/v1/organizations/{org_id}

Update organization name or settings. Requires admin role.

namestring

New organization name.

settingsobject

Organization settings to update.

200Response
{
  "id": "org_abc123",
  "name": "Acme Engineering (Updated)",
  "updated_at": "2026-01-16T09:00:00Z"
}

Delete organization

DELETE/v1/organizations/{org_id}

Permanently delete an organization and all its data. Requires admin role. This is irreversible.

confirmbooleanrequired

Must be true to proceed. Safety check.

200Response
{
  "deleted": true,
  "id": "org_abc123",
  "data_retention_days": 30
}
Danger

Organization deletion schedules all data for permanent erasure after 30 days. You can reactivate within this period by contacting support.

Invite member

POST/v1/organizations/{org_id}/invitations

Send an email invitation to join the organization. Requires admin role.

emailstringrequired

Email address to invite.

rolestringDefault: member

Role to assign: admin or member.

201Response
{
  "id": "inv_abc123",
  "email": "[email protected]",
  "role": "member",
  "status": "pending",
  "expires_at": "2026-01-22T10:00:00Z",
  "invited_by": "usr_xyz789"
}

List members

GET/v1/organizations/{org_id}/members

List all members and pending invitations for the organization.

200Response
{
  "data": [
    {
      "id": "mem_xyz789",
      "email": "[email protected]",
      "name": "Alice",
      "role": "admin",
      "status": "active",
      "joined_at": "2026-01-15T10:00:00Z"
    },
    {
      "id": "mem_def456",
      "email": "[email protected]",
      "name": "Bob",
      "role": "member",
      "status": "active",
      "joined_at": "2026-01-16T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 2,
    "total_pages": 1
  }
}

Update member role

PATCH/v1/organizations/{org_id}/members/{member_id}

Change a member's role. Requires admin role.

rolestringrequired

New role: admin or member.

200Response
{
  "id": "mem_def456",
  "role": "admin",
  "updated_at": "2026-01-17T10:00:00Z"
}

Remove member

DELETE/v1/organizations/{org_id}/members/{member_id}

Remove a member from the organization. Their personal data is not affected.

200Response
{
  "removed": true,
  "member_id": "mem_def456",
  "keys_revoked": 1
}

Create API key

POST/v1/organizations/{org_id}/api-keys

Create a new API key for the organization. Requires admin role.

namestringrequired

Descriptive name for the key.

scopesarrayrequired

Array of permission scopes. See available scopes.

environmentstringDefault: production

Key environment: production or development.

expires_in_daysinteger

Optional expiration in days from creation.

201Response
{
  "id": "key_abc123",
  "key": "nx_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "name": "Production Backend",
  "scopes": [
    "memory:read",
    "memory:write",
    "engine:consolidate"
  ],
  "environment": "production",
  "created_at": "2026-01-15T10:00:00Z"
}
Danger

The full API key value is only shown once in this response. Store it securely immediately.

List API keys

GET/v1/organizations/{org_id}/api-keys

List all API keys for the organization. Key values are masked.

200Response
{
  "data": [
    {
      "id": "key_abc123",
      "name": "Production Backend",
      "prefix": "nx_live_a1b2",
      "suffix": "o5p6",
      "scopes": [
        "memory:read",
        "memory:write",
        "engine:consolidate"
      ],
      "environment": "production",
      "last_used_at": "2026-01-20T14:30:00Z",
      "created_at": "2026-01-15T10:00:00Z"
    }
  ]
}

Rotate API key

POST/v1/organizations/{org_id}/api-keys/{key_id}/rotate

Rotate an API key. Creates a new key and gives the old one a grace period before expiry.

grace_period_hoursintegerDefault: 24

Hours the old key remains valid after rotation.

200Response
{
  "new_key": "nx_live_z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4",
  "old_key_expires_at": "2026-01-16T10:00:00Z",
  "grace_period_hours": 24
}

Revoke API key

DELETE/v1/organizations/{org_id}/api-keys/{key_id}

Immediately revoke an API key. No grace period.

200Response
{
  "revoked": true,
  "key_id": "key_abc123",
  "revoked_at": "2026-01-15T10:00:00Z"
}
Warning

Revoking is immediate. All requests using this key will receive 401 errors instantly.

Next steps

Engine AdvancedBilling