Organizations API
PUT /api/v1/branding/organizations/{org_id}/branding
Summary: Update organization branding
Update branding configuration including colors, fonts, logos, and theme
Request Schema (BrandingUpdate):
| Property | Type | Required | Description |
|---|---|---|---|
logo_url | any | Logo URL (hosted or uploaded) | |
favicon_url | any | Favicon URL | |
company_name | any | Company name | |
primary_color | any | Primary brand color (hex) | |
secondary_color | any | Secondary color (hex) | |
accent_color | any | Accent color (hex) | |
background_color | any | Background color (hex) | |
text_color | any | Primary text color (hex) | |
font_family | any | Font family (e.g., 'Inter', 'Roboto') | |
theme | any | Predefined theme | |
custom_css | any | Custom CSS for advanced customization |
Response Schema (BrandingResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
org_id | string | * | |
logo_url | any | * | |
favicon_url | any | * | |
company_name | any | * | |
primary_color | string | * | |
secondary_color | string | * | |
accent_color | string | * | |
background_color | string | * | |
text_color | string | * | |
font_family | string | * | |
theme | string | * | |
custom_domain | any | * | |
custom_css | any | * | |
css_variables | object | * |
GET /api/v1/branding/organizations/{org_id}/branding
Summary: Get organization branding
Retrieve current branding configuration for organization
Response Schema (BrandingResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
org_id | string | * | |
logo_url | any | * | |
favicon_url | any | * | |
company_name | any | * | |
primary_color | string | * | |
secondary_color | string | * | |
accent_color | string | * | |
background_color | string | * | |
text_color | string | * | |
font_family | string | * | |
theme | string | * | |
custom_domain | any | * | |
custom_css | any | * | |
css_variables | object | * |
GET /api/v1/branding/organizations/{org_id}/css-variables
Summary: Get CSS variables
Get generated CSS custom properties for organization branding
POST /api/v1/branding/organizations/{org_id}/logo
Summary: Upload organization logo
Upload a logo image for organization branding
Response Schema (LogoUploadResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
logo_url | string | * | |
thumbnail_url | any | * | |
size_bytes | integer | * | |
dimensions | object | * |
DELETE /api/v1/branding/organizations/{org_id}/logo
Summary: Delete organization logo
Remove logo from organization branding
POST /api/v1/branding/organizations/{org_id}/domain
Summary: Add custom domain
Configure a custom domain for organization
Request Schema (CustomDomainCreate):
| Property | Type | Required | Description |
|---|---|---|---|
domain | string | * | Custom domain (e.g., kb.acme.com) |
Response Schema (CustomDomainResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
domain | string | * | |
status | CustomDomainStatus | * | |
verified_at | any | * | |
ssl_enabled | boolean | * | |
dns_records | object | * |
GET /api/v1/branding/organizations/{org_id}/domain
Summary: Get custom domain status
Retrieve custom domain configuration and status
Response Schema (CustomDomainResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
domain | string | * | |
status | CustomDomainStatus | * | |
verified_at | any | * | |
ssl_enabled | boolean | * | |
dns_records | object | * |
DELETE /api/v1/branding/organizations/{org_id}/domain
Summary: Remove custom domain
Remove custom domain from organization
POST /api/v1/branding/organizations/{org_id}/domain/verify
Summary: Verify custom domain
Verify DNS configuration for custom domain
Response Schema (DomainVerificationResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
verified | boolean | * | |
message | string | * | |
dns_records_found | object | * |
POST /api/v1/organizations/
Summary: Create Organization
Create a new organization (admin only).
Request Schema (app__schemas__user__OrganizationCreate):
| Property | Type | Required | Description |
|---|---|---|---|
name | string | * | Organization name |
description | any | Organization description | |
metadata | any | Additional metadata |
Response Schema (OrganizationResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
name | string | * | |
description | any | ||
metadata | object | ||
created_at | string | * | |
updated_at | string | * | |
slug | any | ||
mode | any | ||
subscription_plan | any | ||
subscription_status | any | ||
status | any | ||
branding | any | ||
features | any | ||
payment_provider | any | ||
api_key_public | any |
GET /api/v1/organizations/{org_id}
Summary: Get Organization
Get organization details.
User must be a member of the organization.
Response Schema (OrganizationResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
name | string | * | |
description | any | ||
metadata | object | ||
created_at | string | * | |
updated_at | string | * | |
slug | any | ||
mode | any | ||
subscription_plan | any | ||
subscription_status | any | ||
status | any | ||
branding | any | ||
features | any | ||
payment_provider | any | ||
api_key_public | any |
PATCH /api/v1/organizations/{org_id}
Summary: Update Organization
Update organization details (admin only).
Only organization admins can update organization details.
Request Schema (app__schemas__user__OrganizationUpdate):
| Property | Type | Required | Description |
|---|---|---|---|
name | any | Organization name | |
description | any | Organization description | |
metadata | any | Additional metadata |
Response Schema (OrganizationResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
name | string | * | |
description | any | ||
metadata | object | ||
created_at | string | * | |
updated_at | string | * | |
slug | any | ||
mode | any | ||
subscription_plan | any | ||
subscription_status | any | ||
status | any | ||
branding | any | ||
features | any | ||
payment_provider | any | ||
api_key_public | any |
GET /api/v1/organizations/{org_id}/users
Summary: List Organization Users
List all users in an organization (admin only).
Only organization admins can list users.
POST /api/v1/organizations/{org_id}/users/invite
Summary: Invite User
Invite a new user to the organization (admin only).
Creates a new user account with a temporary password that should be reset. Only organization admins can invite users.
Request Schema (UserInvite):
| Property | Type | Required | Description |
|---|---|---|---|
email | string | * | User email |
full_name | string | * | Full name |
role | string | * | User role: admin, member, or viewer |
Response Schema (UserResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
email | string | * | |
full_name | string | * | |
org_id | string | * | |
role | string | * | |
is_active | boolean | * | |
avatar_url | any | ||
created_at | string | * | |
name | string | * | Alias for full_name to match frontend expectations |
GET /api/v1/organizations/{org_id}/stats
Summary: Get Organization Stats
Get organization statistics (admin only).
Returns usage metrics for the organization. Only organization admins can view stats.
Response Schema (OrganizationStats - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
total_users | integer | * | |
active_users | integer | * | |
total_projects | integer | * | |
total_documents | integer | * | |
total_queries | integer | * |
GET /api/v1/organizations/{org_id}/collections
Summary: List Collections
List collections in an organization, optionally filtered by project.
- Organization admins see all collections in the org
- Regular users see only collections in projects they are members of
POST /api/v1/organizations/{org_id}/collections
Summary: Create Collection
Create a new collection in an organization within a project.
Requires:
- project_id must be provided
- User must be a project member (at least 'member' role) or org admin
Request Schema (CollectionCreate):
| Property | Type | Required | Description |
|---|---|---|---|
name | string | * | Collection name |
description | any | Collection description | |
project_id | any | Project ID (required for new collections) | |
metadata | any | Additional metadata |
Response Schema (CollectionResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
name | string | * | |
description | any | * | |
metadata | object | * | |
document_count | integer | ||
project_id | any | ||
org_id | any | ||
created_at | string | * | |
updated_at | string | * |
PATCH /api/v1/organizations/{org_id}/collections/{collection_id}
Summary: Update Collection
Update a collection's name, description, or metadata.
Request Schema (CollectionUpdate):
| Property | Type | Required | Description |
|---|---|---|---|
name | any | Collection name | |
description | any | Collection description | |
metadata | any | Additional metadata |
Response Schema (CollectionResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
name | string | * | |
description | any | * | |
metadata | object | * | |
document_count | integer | ||
project_id | any | ||
org_id | any | ||
created_at | string | * | |
updated_at | string | * |
DELETE /api/v1/organizations/{org_id}/collections/{collection_id}
Summary: Delete Collection
Delete a collection. Documents in the collection are detached (collection_id set NULL).
POST /api/v1/organizations/admin/organizations
Summary: Provision Organization
Provision a new organization (tenant) with an owner user. Platform admin only.
Request Schema (app__schemas__organization__OrganizationCreate):
| Property | Type | Required | Description |
|---|---|---|---|
name | string | * | Organization name |
slug | string | * | Organization slug (URL-safe) |
mode | string | * | Default mode: knowledge_base, advisor, documentation |
subscription_plan | string | Initial subscription plan | |
owner_email | string | * | Owner email address |
branding | any | Branding configuration | |
features | any | Feature flags |
Response Schema (OrganizationResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
name | string | * | |
description | any | ||
metadata | object | ||
created_at | string | * | |
updated_at | string | * | |
slug | any | ||
mode | any | ||
subscription_plan | any | ||
subscription_status | any | ||
status | any | ||
branding | any | ||
features | any | ||
payment_provider | any | ||
api_key_public | any |
GET /api/v1/organizations
Summary: List Organizations
List organizations. Platform admins see all; others see only their own.
PATCH /api/v1/organizations/{org_id}/settings
Summary: Update Organization Settings
Update tenant settings (name, branding, features, domain config). Org admin only.
Request Schema (app__schemas__organization__OrganizationUpdate):
| Property | Type | Required | Description |
|---|---|---|---|
name | any | Organization name | |
branding | any | Branding configuration | |
features | any | Feature flags | |
domain_config | any | Domain-specific configuration |
Response Schema (OrganizationResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
name | string | * | |
description | any | ||
metadata | object | ||
created_at | string | * | |
updated_at | string | * | |
slug | any | ||
mode | any | ||
subscription_plan | any | ||
subscription_status | any | ||
status | any | ||
branding | any | ||
features | any | ||
payment_provider | any | ||
api_key_public | any |
GET /api/v1/organizations/{org_id}/usage
Summary: Get Organization Usage
Get usage metrics and plan limits for the current billing period.
Response Schema (OrgUsageResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
period_start | string | * | |
period_end | string | * | |
documents | object | * | |
users | object | * | |
queries | object | * | |
storage | object | * | |
api_calls | object | * |
POST /api/v1/organizations/{org_id}/subscription/upgrade
Summary: Upgrade Subscription
Upgrade the subscription plan (integrates with Stripe). Org admin only.
Request Schema (SubscriptionUpgrade):
| Property | Type | Required | Description |
|---|---|---|---|
plan | string | * | New plan: free, pro, enterprise |
payment_method_id | any | Stripe payment method ID |
Response Schema (OrganizationResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
name | string | * | |
description | any | ||
metadata | object | ||
created_at | string | * | |
updated_at | string | * | |
slug | any | ||
mode | any | ||
subscription_plan | any | ||
subscription_status | any | ||
status | any | ||
branding | any | ||
features | any | ||
payment_provider | any | ||
api_key_public | any |
POST /api/v1/organizations/{org_id}/subscription/cancel
Summary: Cancel Subscription
Cancel the subscription (immediately or at period end). Org admin only.
Request Schema (app__schemas__organization__SubscriptionCancel):
| Property | Type | Required | Description |
|---|---|---|---|
cancel_at_period_end | boolean | Cancel at end of billing period | |
feedback | any | Cancellation feedback |
Response Schema (OrganizationResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
name | string | * | |
description | any | ||
metadata | object | ||
created_at | string | * | |
updated_at | string | * | |
slug | any | ||
mode | any | ||
subscription_plan | any | ||
subscription_status | any | ||
status | any | ||
branding | any | ||
features | any | ||
payment_provider | any | ||
api_key_public | any |
POST /api/v1/organizations/{org_id}/api-keys/regenerate
Summary: Regenerate Api Keys
Regenerate API keys (old keys are revoked immediately). Org admin only.
Response Schema (OrganizationAPIKeysResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
public_key | string | * | |
secret_key | string | * |
POST /api/v1/organizations/{org_id}/pause
Summary: Pause Organization
Suspend the organization (sets status='suspended'). Org admin only.
Response Schema (OrganizationResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
name | string | * | |
description | any | ||
metadata | object | ||
created_at | string | * | |
updated_at | string | * | |
slug | any | ||
mode | any | ||
subscription_plan | any | ||
subscription_status | any | ||
status | any | ||
branding | any | ||
features | any | ||
payment_provider | any | ||
api_key_public | any |
POST /api/v1/organizations/{org_id}/resume
Summary: Resume Organization
Reactivate a suspended organization (sets status='active'). Org admin only.
Response Schema (OrganizationResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
id | string | * | |
name | string | * | |
description | any | ||
metadata | object | ||
created_at | string | * | |
updated_at | string | * | |
slug | any | ||
mode | any | ||
subscription_plan | any | ||
subscription_status | any | ||
status | any | ||
branding | any | ||
features | any | ||
payment_provider | any | ||
api_key_public | any |
GET /api/v1/organizations/{org_id}/analytics
Summary: Get Organization Analytics
Return usage analytics for the organization's current billing period.
GET /api/v1/organizations/{org_id}/logs
Summary: Get Organization Logs
Return recent audit-log entries for the organization. Org admin only.
POST /api/v1/organizations/{org_id}/test
Summary: Test Organization
Run lightweight readiness checks for the organization tenant. Org admin only.
POST /api/v1/billing/organizations/{org_id}/subscription
Summary: Create Subscription
Create or upgrade organization subscription.
Requires payment method for paid plans (Pro, Enterprise). Supports optional trial period.
Request Schema (SubscriptionCreate):
| Property | Type | Required | Description |
|---|---|---|---|
plan | SubscriptionPlan | * | Subscription plan |
payment_provider | PaymentProvider | Payment provider (stripe or paystack) | |
payment_method_id | any | Payment method ID (Stripe) or authorization code (Paystack) | |
trial_days | integer | Trial period in days |
Response Schema (SubscriptionResponse - Status 201):
| Property | Type | Required | Description |
|---|---|---|---|
org_id | string | * | |
plan | string | * | |
status | string | * | |
stripe_customer_id | any | * | |
stripe_subscription_id | any | * | |
current_period_start | string | * | |
current_period_end | string | * | |
cancel_at_period_end | boolean | * | |
trial_end | any | * | |
created_at | string | * | |
max_documents | integer | * | |
max_users | integer | * | |
max_queries_per_month | integer | * | |
max_storage_gb | number | * | |
current_documents | integer | * | |
current_users | integer | * | |
current_queries | integer | * | |
current_storage_gb | number | * | |
has_overages | boolean | * | |
overage_details | any | * |
PATCH /api/v1/billing/organizations/{org_id}/subscription
Summary: Update Subscription
Update organization subscription (change plan).
Supports upgrade/downgrade with automatic proration.
Request Schema (SubscriptionUpdate):
| Property | Type | Required | Description |
|---|---|---|---|
plan | SubscriptionPlan | * | New subscription plan |
proration | boolean | Apply proration for plan changes |
Response Schema (SubscriptionResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
org_id | string | * | |
plan | string | * | |
status | string | * | |
stripe_customer_id | any | * | |
stripe_subscription_id | any | * | |
current_period_start | string | * | |
current_period_end | string | * | |
cancel_at_period_end | boolean | * | |
trial_end | any | * | |
created_at | string | * | |
max_documents | integer | * | |
max_users | integer | * | |
max_queries_per_month | integer | * | |
max_storage_gb | number | * | |
current_documents | integer | * | |
current_users | integer | * | |
current_queries | integer | * | |
current_storage_gb | number | * | |
has_overages | boolean | * | |
overage_details | any | * |
DELETE /api/v1/billing/organizations/{org_id}/subscription
Summary: Cancel Subscription
Cancel organization subscription.
Can cancel immediately or at end of billing period.
Request Schema (app__schemas__subscription__SubscriptionCancel):
| Property | Type | Required | Description |
|---|---|---|---|
cancel_at_period_end | boolean | Cancel at end of billing period (no refund) or immediately | |
feedback | any | Cancellation reason |
GET /api/v1/billing/organizations/{org_id}/subscription
Summary: Get Subscription
Retrieve current subscription snapshot for a organization.
Response Schema (SubscriptionResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
org_id | string | * | |
plan | string | * | |
status | string | * | |
stripe_customer_id | any | * | |
stripe_subscription_id | any | * | |
current_period_start | string | * | |
current_period_end | string | * | |
cancel_at_period_end | boolean | * | |
trial_end | any | * | |
created_at | string | * | |
max_documents | integer | * | |
max_users | integer | * | |
max_queries_per_month | integer | * | |
max_storage_gb | number | * | |
current_documents | integer | * | |
current_users | integer | * | |
current_queries | integer | * | |
current_storage_gb | number | * | |
has_overages | boolean | * | |
overage_details | any | * |
GET /api/v1/billing/organizations/{org_id}/usage
Summary: Get Usage Metrics
Return current-period usage metrics for a organization.
Response Schema (UsageMetrics - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
documents | object | * | |
users | object | * | |
queries | object | * | |
storage | object | * |
GET /api/v1/billing/organizations/{org_id}/entitlements
Summary: Get Entitlements
Return the organization's resolved entitlements (flags + limits).
Renders the full entitlement catalog (see
services.billing.entitlements.ENTITLEMENT_CATALOG) against the org's
computed features, so clients can drive UI gating from one place instead
of reading individual feature keys ad hoc.
POST /api/v1/billing/organizations/{org_id}/payment-methods
Summary: Attach Payment Method
Attach payment method to organization.
Payment method ID should be obtained from Stripe.js on frontend.
Request Schema (PaymentMethodAttach):
| Property | Type | Required | Description |
|---|---|---|---|
payment_method_id | string | * | Stripe payment method ID from Stripe.js |
set_as_default | boolean | Set as default payment method |
GET /api/v1/billing/organizations/{org_id}/payment-methods
Summary: List Payment Methods
List all payment methods for organization
Response Schema (PaymentMethodListResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
payment_methods | array of PaymentMethodResponse | * | |
default_payment_method_id | any | * |
GET /api/v1/billing/organizations/{org_id}/invoices
Summary: List Invoices
List invoices for organization
Response Schema (InvoiceListResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
invoices | array of InvoiceResponse | * | |
total | integer | * |
POST /api/v1/billing/organizations/{org_id}/billing-portal
Summary: Create Billing Portal Session
Create Stripe billing portal session.
Redirects to Stripe hosted page for managing subscription and payment methods.
Response Schema (BillingPortalSessionResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
url | string | * | URL to Stripe billing portal |
GET /api/v1/billing/organizations/{org_id}/usage/overages
Summary: Check Overages
Check for usage overages.
Returns alerts for resources nearing or exceeding limits.
Response Schema (OverageResponse - Status 200):
| Property | Type | Required | Description |
|---|---|---|---|
has_overages | boolean | * | |
alerts | array of OverageAlert | * | |
recommendation | any | * |
GET /api/v1/billing/organizations/{org_id}/addons
Summary: List Org Addons
List an organization's active add-ons.
POST /api/v1/billing/organizations/{org_id}/addons
Summary: Add Org Addon
Add (or increase) an add-on. Admin only.
DELETE /api/v1/billing/organizations/{org_id}/addons/{key}
Summary: Remove Org Addon
Cancel a recurring add-on. Admin only.