# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand. overlay: 1.0.0 info: title: API Evangelist conversational phrasing for Clerk Backend Organizations API version: 1.0.0 extends: openapi/clerk-com-organizations-api-openapi.yml actions: - target: $.info update: x-apievangelist-phrasing: method: generated generated: '2026-09-26' generator: build-phrasing.py label: Generated by API Evangelist operations: 11 - target: $.paths['/organizations'].get update: x-apievangelist-phrasing: intent: List organizations in the instance effect: read questions: - How do I list every organization in my instance, newest first? - Can I include member counts when listing organizations? - Which organizations does a given user belong to across the instance? instructions: - text: List all organizations with their member counts. - text: Search organizations matching {query}. slots: query: query.query - text: List the organizations that user {user_id} belongs to. slots: user_id: query.user_id method: generated generated: '2026-09-26' - target: $.paths['/organizations'].post update: x-apievangelist-phrasing: intent: Create an organization effect: write questions: - How do I create an organization for a customer from my backend? - Can I set a custom slug and a membership cap when creating an organization? - What characters are allowed in an organization slug? instructions: - text: Create an organization named {name}. slots: name: requestBody.name - text: Create organization {name} with slug {slug}, owned by user {created_by}. slots: name: requestBody.name slug: requestBody.slug created_by: requestBody.created_by - text: Create organization {name} capped at {max_allowed_memberships} members. slots: name: requestBody.name max_allowed_memberships: requestBody.max_allowed_memberships method: generated generated: '2026-09-26' - target: $.paths['/organizations/{organization_id}'].get update: x-apievangelist-phrasing: intent: Retrieve an organization by ID or slug effect: read questions: - How do I fetch one organization by its ID or slug? - Can I get a single organization's member count along with its details? instructions: - text: Get organization {organization_id}. slots: organization_id: path.organization_id - text: Show the details and member count of organization {organization_id}. slots: organization_id: path.organization_id method: generated generated: '2026-09-26' - target: $.paths['/organizations/{organization_id}'].delete update: x-apievangelist-phrasing: intent: Delete an organization effect: destructive questions: - How do I permanently delete an organization and its memberships? - Is deleting an organization reversible? instructions: - text: Delete organization {organization_id}. slots: organization_id: path.organization_id - text: Permanently remove organization {organization_id} with all its memberships and invitations. slots: organization_id: path.organization_id method: generated generated: '2026-09-26' - target: $.paths['/organizations/{organization_id}'].patch update: x-apievangelist-phrasing: intent: Update an organization effect: write questions: - How do I rename an organization or change its slug from the backend? - Can I raise the maximum allowed memberships on an existing organization? instructions: - text: Rename organization {organization_id} to {name}. slots: organization_id: path.organization_id name: requestBody.name - text: Change the slug of organization {organization_id} to {slug}. slots: organization_id: path.organization_id slug: requestBody.slug - text: Set the member cap of organization {organization_id} to {max_allowed_memberships}. slots: organization_id: path.organization_id max_allowed_memberships: requestBody.max_allowed_memberships method: generated generated: '2026-09-26' - target: $.paths['/organizations/{organization_id}/metadata'].patch update: x-apievangelist-phrasing: intent: Merge metadata into an organization effect: write questions: - How do I add a key to an organization's metadata without replacing the rest? - Does organization metadata merging handle nested JSON? instructions: - text: Merge {private_metadata} into the private metadata of organization {organization_id}. slots: private_metadata: requestBody.private_metadata organization_id: path.organization_id - text: Deep-merge {public_metadata} into organization {organization_id}'s public metadata. slots: public_metadata: requestBody.public_metadata organization_id: path.organization_id method: generated generated: '2026-09-26' - target: $.paths['/organizations/{organization_id}/logo'].put update: x-apievangelist-phrasing: intent: Upload an organization's logo effect: write questions: - How do I upload a logo image for an organization from the backend? - What is the maximum file size for an organization logo? instructions: - text: Upload {file} as the logo of organization {organization_id}. slots: file: requestBody.file organization_id: path.organization_id - text: Replace the logo of organization {organization_id} with {file}, uploaded by user {uploader_user_id}. slots: organization_id: path.organization_id file: requestBody.file uploader_user_id: requestBody.uploader_user_id method: generated generated: '2026-09-26' - target: $.paths['/organizations/{organization_id}/logo'].delete update: x-apievangelist-phrasing: intent: Delete an organization's logo effect: destructive questions: - How do I remove an organization's logo from the backend? - Can an admin clear an organization logo without uploading a new one? instructions: - text: Delete the logo of organization {organization_id}. slots: organization_id: path.organization_id - text: Clear the organization logo on {organization_id}. slots: organization_id: path.organization_id method: generated generated: '2026-09-26' - target: $.paths['/organizations/{organization_id}/billing/subscription'].get update: x-apievangelist-phrasing: intent: Get an organization's billing subscription effect: read questions: - Which plans is an organization currently subscribed to? - How do I check an organization's subscription payment status? instructions: - text: Show the billing subscription for organization {organization_id}. slots: organization_id: path.organization_id - text: Get the active plans and payment status of organization {organization_id}. slots: organization_id: path.organization_id method: generated generated: '2026-09-26' - target: $.paths['/organizations/{organization_id}/billing/credits'].get update: x-apievangelist-phrasing: intent: Get an organization's credit balance effect: read questions: - How much billing credit does an organization have left? - Can I see an organization's credits before its next recurring charge? instructions: - text: Show the credit balance of organization {organization_id}. slots: organization_id: path.organization_id - text: Look up how many credits organization {organization_id} has available. slots: organization_id: path.organization_id method: generated generated: '2026-09-26' - target: $.paths['/organizations/{organization_id}/billing/credits'].post update: x-apievangelist-phrasing: intent: Adjust an organization's credit balance effect: write questions: - How do I grant billing credit to an organization? - Can I decrease an organization's credits, and are duplicate adjustments safe? instructions: - text: Increase organization {organization_id}'s credits by {amount} with idempotency key {idempotency_key}. slots: organization_id: path.organization_id amount: requestBody.amount idempotency_key: requestBody.idempotency_key - text: Apply a {action} of {amount} to organization {organization_id}'s credits with note {note} and key {idempotency_key}. slots: action: requestBody.action amount: requestBody.amount organization_id: path.organization_id note: requestBody.note idempotency_key: requestBody.idempotency_key method: generated generated: '2026-09-26'