Pragence

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):

PropertyTypeRequiredDescription
logo_urlanyLogo URL (hosted or uploaded)
favicon_urlanyFavicon URL
company_nameanyCompany name
primary_coloranyPrimary brand color (hex)
secondary_coloranySecondary color (hex)
accent_coloranyAccent color (hex)
background_coloranyBackground color (hex)
text_coloranyPrimary text color (hex)
font_familyanyFont family (e.g., 'Inter', 'Roboto')
themeanyPredefined theme
custom_cssanyCustom CSS for advanced customization

Response Schema (BrandingResponse - Status 200):

PropertyTypeRequiredDescription
org_idstring*
logo_urlany*
favicon_urlany*
company_nameany*
primary_colorstring*
secondary_colorstring*
accent_colorstring*
background_colorstring*
text_colorstring*
font_familystring*
themestring*
custom_domainany*
custom_cssany*
css_variablesobject*

GET /api/v1/branding/organizations/{org_id}/branding

Summary: Get organization branding

Retrieve current branding configuration for organization

Response Schema (BrandingResponse - Status 200):

PropertyTypeRequiredDescription
org_idstring*
logo_urlany*
favicon_urlany*
company_nameany*
primary_colorstring*
secondary_colorstring*
accent_colorstring*
background_colorstring*
text_colorstring*
font_familystring*
themestring*
custom_domainany*
custom_cssany*
css_variablesobject*

GET /api/v1/branding/organizations/{org_id}/css-variables

Summary: Get CSS variables

Get generated CSS custom properties for organization branding


Summary: Upload organization logo

Upload a logo image for organization branding

Response Schema (LogoUploadResponse - Status 201):

PropertyTypeRequiredDescription
logo_urlstring*
thumbnail_urlany*
size_bytesinteger*
dimensionsobject*

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):

PropertyTypeRequiredDescription
domainstring*Custom domain (e.g., kb.acme.com)

Response Schema (CustomDomainResponse - Status 201):

PropertyTypeRequiredDescription
domainstring*
statusCustomDomainStatus*
verified_atany*
ssl_enabledboolean*
dns_recordsobject*

GET /api/v1/branding/organizations/{org_id}/domain

Summary: Get custom domain status

Retrieve custom domain configuration and status

Response Schema (CustomDomainResponse - Status 200):

PropertyTypeRequiredDescription
domainstring*
statusCustomDomainStatus*
verified_atany*
ssl_enabledboolean*
dns_recordsobject*

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):

PropertyTypeRequiredDescription
verifiedboolean*
messagestring*
dns_records_foundobject*

POST /api/v1/organizations/

Summary: Create Organization

Create a new organization (admin only).

Request Schema (app__schemas__user__OrganizationCreate):

PropertyTypeRequiredDescription
namestring*Organization name
descriptionanyOrganization description
metadataanyAdditional metadata

Response Schema (OrganizationResponse - Status 200):

PropertyTypeRequiredDescription
idstring*
namestring*
descriptionany
metadataobject
created_atstring*
updated_atstring*
slugany
modeany
subscription_planany
subscription_statusany
statusany
brandingany
featuresany
payment_providerany
api_key_publicany

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):

PropertyTypeRequiredDescription
idstring*
namestring*
descriptionany
metadataobject
created_atstring*
updated_atstring*
slugany
modeany
subscription_planany
subscription_statusany
statusany
brandingany
featuresany
payment_providerany
api_key_publicany

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):

PropertyTypeRequiredDescription
nameanyOrganization name
descriptionanyOrganization description
metadataanyAdditional metadata

Response Schema (OrganizationResponse - Status 200):

PropertyTypeRequiredDescription
idstring*
namestring*
descriptionany
metadataobject
created_atstring*
updated_atstring*
slugany
modeany
subscription_planany
subscription_statusany
statusany
brandingany
featuresany
payment_providerany
api_key_publicany

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):

PropertyTypeRequiredDescription
emailstring*User email
full_namestring*Full name
rolestring*User role: admin, member, or viewer

Response Schema (UserResponse - Status 201):

PropertyTypeRequiredDescription
idstring*
emailstring*
full_namestring*
org_idstring*
rolestring*
is_activeboolean*
avatar_urlany
created_atstring*
namestring*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):

PropertyTypeRequiredDescription
total_usersinteger*
active_usersinteger*
total_projectsinteger*
total_documentsinteger*
total_queriesinteger*

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):

PropertyTypeRequiredDescription
namestring*Collection name
descriptionanyCollection description
project_idanyProject ID (required for new collections)
metadataanyAdditional metadata

Response Schema (CollectionResponse - Status 200):

PropertyTypeRequiredDescription
idstring*
namestring*
descriptionany*
metadataobject*
document_countinteger
project_idany
org_idany
created_atstring*
updated_atstring*

PATCH /api/v1/organizations/{org_id}/collections/{collection_id}

Summary: Update Collection

Update a collection's name, description, or metadata.

Request Schema (CollectionUpdate):

PropertyTypeRequiredDescription
nameanyCollection name
descriptionanyCollection description
metadataanyAdditional metadata

Response Schema (CollectionResponse - Status 200):

PropertyTypeRequiredDescription
idstring*
namestring*
descriptionany*
metadataobject*
document_countinteger
project_idany
org_idany
created_atstring*
updated_atstring*

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):

PropertyTypeRequiredDescription
namestring*Organization name
slugstring*Organization slug (URL-safe)
modestring*Default mode: knowledge_base, advisor, documentation
subscription_planstringInitial subscription plan
owner_emailstring*Owner email address
brandinganyBranding configuration
featuresanyFeature flags

Response Schema (OrganizationResponse - Status 201):

PropertyTypeRequiredDescription
idstring*
namestring*
descriptionany
metadataobject
created_atstring*
updated_atstring*
slugany
modeany
subscription_planany
subscription_statusany
statusany
brandingany
featuresany
payment_providerany
api_key_publicany

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):

PropertyTypeRequiredDescription
nameanyOrganization name
brandinganyBranding configuration
featuresanyFeature flags
domain_configanyDomain-specific configuration

Response Schema (OrganizationResponse - Status 200):

PropertyTypeRequiredDescription
idstring*
namestring*
descriptionany
metadataobject
created_atstring*
updated_atstring*
slugany
modeany
subscription_planany
subscription_statusany
statusany
brandingany
featuresany
payment_providerany
api_key_publicany

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):

PropertyTypeRequiredDescription
period_startstring*
period_endstring*
documentsobject*
usersobject*
queriesobject*
storageobject*
api_callsobject*

POST /api/v1/organizations/{org_id}/subscription/upgrade

Summary: Upgrade Subscription

Upgrade the subscription plan (integrates with Stripe). Org admin only.

Request Schema (SubscriptionUpgrade):

PropertyTypeRequiredDescription
planstring*New plan: free, pro, enterprise
payment_method_idanyStripe payment method ID

Response Schema (OrganizationResponse - Status 200):

PropertyTypeRequiredDescription
idstring*
namestring*
descriptionany
metadataobject
created_atstring*
updated_atstring*
slugany
modeany
subscription_planany
subscription_statusany
statusany
brandingany
featuresany
payment_providerany
api_key_publicany

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):

PropertyTypeRequiredDescription
cancel_at_period_endbooleanCancel at end of billing period
feedbackanyCancellation feedback

Response Schema (OrganizationResponse - Status 200):

PropertyTypeRequiredDescription
idstring*
namestring*
descriptionany
metadataobject
created_atstring*
updated_atstring*
slugany
modeany
subscription_planany
subscription_statusany
statusany
brandingany
featuresany
payment_providerany
api_key_publicany

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):

PropertyTypeRequiredDescription
public_keystring*
secret_keystring*

POST /api/v1/organizations/{org_id}/pause

Summary: Pause Organization

Suspend the organization (sets status='suspended'). Org admin only.

Response Schema (OrganizationResponse - Status 200):

PropertyTypeRequiredDescription
idstring*
namestring*
descriptionany
metadataobject
created_atstring*
updated_atstring*
slugany
modeany
subscription_planany
subscription_statusany
statusany
brandingany
featuresany
payment_providerany
api_key_publicany

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):

PropertyTypeRequiredDescription
idstring*
namestring*
descriptionany
metadataobject
created_atstring*
updated_atstring*
slugany
modeany
subscription_planany
subscription_statusany
statusany
brandingany
featuresany
payment_providerany
api_key_publicany

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):

PropertyTypeRequiredDescription
planSubscriptionPlan*Subscription plan
payment_providerPaymentProviderPayment provider (stripe or paystack)
payment_method_idanyPayment method ID (Stripe) or authorization code (Paystack)
trial_daysintegerTrial period in days

Response Schema (SubscriptionResponse - Status 201):

PropertyTypeRequiredDescription
org_idstring*
planstring*
statusstring*
stripe_customer_idany*
stripe_subscription_idany*
current_period_startstring*
current_period_endstring*
cancel_at_period_endboolean*
trial_endany*
created_atstring*
max_documentsinteger*
max_usersinteger*
max_queries_per_monthinteger*
max_storage_gbnumber*
current_documentsinteger*
current_usersinteger*
current_queriesinteger*
current_storage_gbnumber*
has_overagesboolean*
overage_detailsany*

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):

PropertyTypeRequiredDescription
planSubscriptionPlan*New subscription plan
prorationbooleanApply proration for plan changes

Response Schema (SubscriptionResponse - Status 200):

PropertyTypeRequiredDescription
org_idstring*
planstring*
statusstring*
stripe_customer_idany*
stripe_subscription_idany*
current_period_startstring*
current_period_endstring*
cancel_at_period_endboolean*
trial_endany*
created_atstring*
max_documentsinteger*
max_usersinteger*
max_queries_per_monthinteger*
max_storage_gbnumber*
current_documentsinteger*
current_usersinteger*
current_queriesinteger*
current_storage_gbnumber*
has_overagesboolean*
overage_detailsany*

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):

PropertyTypeRequiredDescription
cancel_at_period_endbooleanCancel at end of billing period (no refund) or immediately
feedbackanyCancellation reason

GET /api/v1/billing/organizations/{org_id}/subscription

Summary: Get Subscription

Retrieve current subscription snapshot for a organization.

Response Schema (SubscriptionResponse - Status 200):

PropertyTypeRequiredDescription
org_idstring*
planstring*
statusstring*
stripe_customer_idany*
stripe_subscription_idany*
current_period_startstring*
current_period_endstring*
cancel_at_period_endboolean*
trial_endany*
created_atstring*
max_documentsinteger*
max_usersinteger*
max_queries_per_monthinteger*
max_storage_gbnumber*
current_documentsinteger*
current_usersinteger*
current_queriesinteger*
current_storage_gbnumber*
has_overagesboolean*
overage_detailsany*

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):

PropertyTypeRequiredDescription
documentsobject*
usersobject*
queriesobject*
storageobject*

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):

PropertyTypeRequiredDescription
payment_method_idstring*Stripe payment method ID from Stripe.js
set_as_defaultbooleanSet 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):

PropertyTypeRequiredDescription
payment_methodsarray of PaymentMethodResponse*
default_payment_method_idany*

GET /api/v1/billing/organizations/{org_id}/invoices

Summary: List Invoices

List invoices for organization

Response Schema (InvoiceListResponse - Status 200):

PropertyTypeRequiredDescription
invoicesarray of InvoiceResponse*
totalinteger*

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):

PropertyTypeRequiredDescription
urlstring*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):

PropertyTypeRequiredDescription
has_overagesboolean*
alertsarray of OverageAlert*
recommendationany*

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.


On this page

Organizations APIPUT /api/v1/branding/organizations/{org_id}/brandingGET /api/v1/branding/organizations/{org_id}/brandingGET /api/v1/branding/organizations/{org_id}/css-variablesPOST /api/v1/branding/organizations/{org_id}/logoDELETE /api/v1/branding/organizations/{org_id}/logoPOST /api/v1/branding/organizations/{org_id}/domainGET /api/v1/branding/organizations/{org_id}/domainDELETE /api/v1/branding/organizations/{org_id}/domainPOST /api/v1/branding/organizations/{org_id}/domain/verifyPOST /api/v1/organizations/GET /api/v1/organizations/{org_id}PATCH /api/v1/organizations/{org_id}GET /api/v1/organizations/{org_id}/usersPOST /api/v1/organizations/{org_id}/users/inviteGET /api/v1/organizations/{org_id}/statsGET /api/v1/organizations/{org_id}/collectionsPOST /api/v1/organizations/{org_id}/collectionsPATCH /api/v1/organizations/{org_id}/collections/{collection_id}DELETE /api/v1/organizations/{org_id}/collections/{collection_id}POST /api/v1/organizations/admin/organizationsGET /api/v1/organizationsPATCH /api/v1/organizations/{org_id}/settingsGET /api/v1/organizations/{org_id}/usagePOST /api/v1/organizations/{org_id}/subscription/upgradePOST /api/v1/organizations/{org_id}/subscription/cancelPOST /api/v1/organizations/{org_id}/api-keys/regeneratePOST /api/v1/organizations/{org_id}/pausePOST /api/v1/organizations/{org_id}/resumeGET /api/v1/organizations/{org_id}/analyticsGET /api/v1/organizations/{org_id}/logsPOST /api/v1/organizations/{org_id}/testPOST /api/v1/billing/organizations/{org_id}/subscriptionPATCH /api/v1/billing/organizations/{org_id}/subscriptionDELETE /api/v1/billing/organizations/{org_id}/subscriptionGET /api/v1/billing/organizations/{org_id}/subscriptionGET /api/v1/billing/organizations/{org_id}/usageGET /api/v1/billing/organizations/{org_id}/entitlementsPOST /api/v1/billing/organizations/{org_id}/payment-methodsGET /api/v1/billing/organizations/{org_id}/payment-methodsGET /api/v1/billing/organizations/{org_id}/invoicesPOST /api/v1/billing/organizations/{org_id}/billing-portalGET /api/v1/billing/organizations/{org_id}/usage/overagesGET /api/v1/billing/organizations/{org_id}/addonsPOST /api/v1/billing/organizations/{org_id}/addonsDELETE /api/v1/billing/organizations/{org_id}/addons/{key}