--- title: "Every client with its organizations, in one call" method: GET path: "/clients_organizations" tags: ["clients"] --- # Every client with its organizations, in one call `GET /clients_organizations` ## Request - Base URL: `https://api.planvortex.com/v1.0.0` - URL: `https://api.planvortex.com/v1.0.0/clients_organizations` - Auth: one of: - HTTP bearer - OAuth 2 (client credentials, token URL `https://api.planvortex.com/v1.0.0/oauth/token`) The whole tree the caller can see: their clients, and inside each one the organizations they have access to. It exists to save the N+1 that building a client picker otherwise costs. **An app always gets exactly one client** — its own — with every organization of it. The two pairs of pagination parameters are independent: `offset`/`limit` page the clients, `offsetOrganizations`/`limitOrganizations` page the organizations inside each one. ## Query parameters - `offset` integer - `limit` integer - `offsetOrganizations` integer - `limitOrganizations` integer - `getUse` boolean ## Response `200` Clients, each with its organizations - object - `clients` object[], required - `_id` string, required - `name` string, required - `client_type` 'personal' | 'company' - `creation_date` string, date-time, required - `trial_tested` boolean: Whether this client has already used its trial. - `actual_plan` ClientsPlan, required: The client's SUBSCRIPTION, which is not the same thing as the resources it grants: the numbers live in `plan_data`. - `enabled` boolean, required: Whether the plan is usable. A disabled client cannot connect accounts or publish. - `status` string, required: The subscription's state at the payment provider (`active`, `past_due`, `canceled`, `trialing`, `unpaid`...). A cancelled subscription still works until `current_period_end`. - `isEnabled` boolean, required: The same thing as `enabled`, recomputed on read rather than stored. Read either; they only disagree if the plan was never saved after changing. - `require_action` boolean: The payment needs the customer to do something (3-D Secure, a new card). - `plan_identifier` 'free' | 'basic' | 'pro' | 'custom', required: Which plan was contracted. `custom` carries its own numbers in `plan_data`. - `plan_data` PlanData, required: The resources a plan grants. On a client it is what was contracted; on an organization, the slice of it that was assigned. The sum across all the organizations of a client can never exceed what the client has contracted. Users are NOT here: every plan has unlimited users, so they are neither charged nor split between organizations. They are still counted, in `PlanUseData.users`. There are no `artificial_inteligence`, `whatsapp` or `stats` flags either: statistics and WhatsApp are on every plan, and what gates AI is `ai_credits` — a plan with credits has AI, and Free has zero. - `accounts` integer, required: Social accounts that may be connected. - `space` number, required: Storage, in GB. - `integrations` integer, required: Connections to a third-party tool material is pulled from (Google Drive, an RSS feed). Not the same thing as an app: an app is API access, and it has its own allowance in `apps`. - `apps` integer: Apps this plan allows: 1 on Free, 2 on Basic, 5 on Pro, 10 on Custom. Each one is a `client_id` with a secret, so each one is a key to the whole public API — which every plan has, Free included. Unlike accounts or storage this is NOT split between organizations: an app belongs to the client. On a use payload it is how many exist right now. - `twitter_credits` integer: Monthly X (Twitter) credits. X bills per use: 15 per post, 200 if the text contains a link, 15 per deletion, 1 per stat read, 1 per timeline item. The pool resets on the 1st of each calendar month and does not roll over. - `ai_credits` integer: Monthly AI credits (1 credit = $0.001 of provider cost): 15 per plan orchestration pass, 2 per generated text, 70 per generated image. Resets monthly and does not roll over. A client using its own provider key (BYOK) does not consume them in that scope. - `current_period_start` string, date-time - `current_period_end` string, date-time: When the current billing period ends. A cancelled plan keeps working until then. - `billing_interval` 'month' | 'year': How often the plan is billed. A yearly plan costs ten monthly fees, paid up front, and every resource in it is still counted per calendar month (AI and X credits included). Clients from before yearly billing existed read `month`. It means nothing on `free`. - `stripe_customer_id` string - `ai_settings` ClientsAiSettings: Per-scope AI provider configuration (BYOK). Only the scopes you send are touched; a scope set to `null` clears its configuration and returns that scope to PlanVortex credits. `orchestrator` and `text` need a text-capable provider, `image` needs an image-capable one. `video` is reserved for a later phase. - `orchestrator` ClientsAiScopeSetting: AI provider configuration for a single scope (BYOK). On write, api_key is required the first time and is stored encrypted; on subsequent writes it can be omitted to keep the existing key (send only provider/model). On read, the api_key is NEVER returned — only has_api_key is exposed. - `provider` 'openrouter' | 'openai' | 'google' | 'anthropic', required: Fixed catalogue of allowed providers. The provider must support the capability of the scope (text for orchestrator/text, image for image). - `model` string, required: Model identifier at the chosen provider (e.g. google/gemini-3-flash). - `api_key` string: Provider API key. Write-only: accepted on PUT, stored encrypted (AES-256-GCM), never returned. - `has_api_key` boolean: Read-only. True when an encrypted API key is stored for this scope. - `text` ClientsAiScopeSetting: AI provider configuration for a single scope (BYOK). On write, api_key is required the first time and is stored encrypted; on subsequent writes it can be omitted to keep the existing key (send only provider/model). On read, the api_key is NEVER returned — only has_api_key is exposed. - `provider` 'openrouter' | 'openai' | 'google' | 'anthropic', required: Fixed catalogue of allowed providers. The provider must support the capability of the scope (text for orchestrator/text, image for image). - `model` string, required: Model identifier at the chosen provider (e.g. google/gemini-3-flash). - `api_key` string: Provider API key. Write-only: accepted on PUT, stored encrypted (AES-256-GCM), never returned. - `has_api_key` boolean: Read-only. True when an encrypted API key is stored for this scope. - `image` ClientsAiScopeSetting: AI provider configuration for a single scope (BYOK). On write, api_key is required the first time and is stored encrypted; on subsequent writes it can be omitted to keep the existing key (send only provider/model). On read, the api_key is NEVER returned — only has_api_key is exposed. - `provider` 'openrouter' | 'openai' | 'google' | 'anthropic', required: Fixed catalogue of allowed providers. The provider must support the capability of the scope (text for orchestrator/text, image for image). - `model` string, required: Model identifier at the chosen provider (e.g. google/gemini-3-flash). - `api_key` string: Provider API key. Write-only: accepted on PUT, stored encrypted (AES-256-GCM), never returned. - `has_api_key` boolean: Read-only. True when an encrypted API key is stored for this scope. - `actual_use` PlanUseData: The resources a plan grants. On a client it is what was contracted; on an organization, the slice of it that was assigned. The sum across all the organizations of a client can never exceed what the client has contracted. Users are NOT here: every plan has unlimited users, so they are neither charged nor split between organizations. They are still counted, in `PlanUseData.users`. There are no `artificial_inteligence`, `whatsapp` or `stats` flags either: statistics and WhatsApp are on every plan, and what gates AI is `ai_credits` — a plan with credits has AI, and Free has zero. - `accounts` integer, required: Social accounts that may be connected. - `space` number, required: Storage, in GB. - `integrations` integer, required: Connections to a third-party tool material is pulled from (Google Drive, an RSS feed). Not the same thing as an app: an app is API access, and it has its own allowance in `apps`. - `apps` integer: Apps this plan allows: 1 on Free, 2 on Basic, 5 on Pro, 10 on Custom. Each one is a `client_id` with a secret, so each one is a key to the whole public API — which every plan has, Free included. Unlike accounts or storage this is NOT split between organizations: an app belongs to the client. On a use payload it is how many exist right now. - `twitter_credits` integer: Monthly X (Twitter) credits. X bills per use: 15 per post, 200 if the text contains a link, 15 per deletion, 1 per stat read, 1 per timeline item. The pool resets on the 1st of each calendar month and does not roll over. - `ai_credits` integer: Monthly AI credits (1 credit = $0.001 of provider cost): 15 per plan orchestration pass, 2 per generated text, 70 per generated image. Resets monthly and does not roll over. A client using its own provider key (BYOK) does not consume them in that scope. - `actual_asigned` PlanData: The resources a plan grants. On a client it is what was contracted; on an organization, the slice of it that was assigned. The sum across all the organizations of a client can never exceed what the client has contracted. Users are NOT here: every plan has unlimited users, so they are neither charged nor split between organizations. They are still counted, in `PlanUseData.users`. There are no `artificial_inteligence`, `whatsapp` or `stats` flags either: statistics and WhatsApp are on every plan, and what gates AI is `ai_credits` — a plan with credits has AI, and Free has zero. - `accounts` integer, required: Social accounts that may be connected. - `space` number, required: Storage, in GB. - `integrations` integer, required: Connections to a third-party tool material is pulled from (Google Drive, an RSS feed). Not the same thing as an app: an app is API access, and it has its own allowance in `apps`. - `apps` integer: Apps this plan allows: 1 on Free, 2 on Basic, 5 on Pro, 10 on Custom. Each one is a `client_id` with a secret, so each one is a key to the whole public API — which every plan has, Free included. Unlike accounts or storage this is NOT split between organizations: an app belongs to the client. On a use payload it is how many exist right now. - `twitter_credits` integer: Monthly X (Twitter) credits. X bills per use: 15 per post, 200 if the text contains a link, 15 per deletion, 1 per stat read, 1 per timeline item. The pool resets on the 1st of each calendar month and does not roll over. - `ai_credits` integer: Monthly AI credits (1 credit = $0.001 of provider cost): 15 per plan orchestration pass, 2 per generated text, 70 per generated image. Resets monthly and does not roll over. A client using its own provider key (BYOK) does not consume them in that scope. - `organizations` Organization[], required - `_id` string, required - `id_client` string, required: The client this organization belongs to. - `name` string, required - `parent_organization` string: The organization this one hangs from. Absent on a root organization. - `creation_date` string, date-time, required - `actual_plan` PlanData: The resources a plan grants. On a client it is what was contracted; on an organization, the slice of it that was assigned. The sum across all the organizations of a client can never exceed what the client has contracted. Users are NOT here: every plan has unlimited users, so they are neither charged nor split between organizations. They are still counted, in `PlanUseData.users`. There are no `artificial_inteligence`, `whatsapp` or `stats` flags either: statistics and WhatsApp are on every plan, and what gates AI is `ai_credits` — a plan with credits has AI, and Free has zero. - `accounts` integer, required: Social accounts that may be connected. - `space` number, required: Storage, in GB. - `integrations` integer, required: Connections to a third-party tool material is pulled from (Google Drive, an RSS feed). Not the same thing as an app: an app is API access, and it has its own allowance in `apps`. - `apps` integer: Apps this plan allows: 1 on Free, 2 on Basic, 5 on Pro, 10 on Custom. Each one is a `client_id` with a secret, so each one is a key to the whole public API — which every plan has, Free included. Unlike accounts or storage this is NOT split between organizations: an app belongs to the client. On a use payload it is how many exist right now. - `twitter_credits` integer: Monthly X (Twitter) credits. X bills per use: 15 per post, 200 if the text contains a link, 15 per deletion, 1 per stat read, 1 per timeline item. The pool resets on the 1st of each calendar month and does not roll over. - `ai_credits` integer: Monthly AI credits (1 credit = $0.001 of provider cost): 15 per plan orchestration pass, 2 per generated text, 70 per generated image. Resets monthly and does not roll over. A client using its own provider key (BYOK) does not consume them in that scope. - `actual_use` PlanUseData: The resources a plan grants. On a client it is what was contracted; on an organization, the slice of it that was assigned. The sum across all the organizations of a client can never exceed what the client has contracted. Users are NOT here: every plan has unlimited users, so they are neither charged nor split between organizations. They are still counted, in `PlanUseData.users`. There are no `artificial_inteligence`, `whatsapp` or `stats` flags either: statistics and WhatsApp are on every plan, and what gates AI is `ai_credits` — a plan with credits has AI, and Free has zero. - `accounts` integer, required: Social accounts that may be connected. - `space` number, required: Storage, in GB. - `integrations` integer, required: Connections to a third-party tool material is pulled from (Google Drive, an RSS feed). Not the same thing as an app: an app is API access, and it has its own allowance in `apps`. - `apps` integer: Apps this plan allows: 1 on Free, 2 on Basic, 5 on Pro, 10 on Custom. Each one is a `client_id` with a secret, so each one is a key to the whole public API — which every plan has, Free included. Unlike accounts or storage this is NOT split between organizations: an app belongs to the client. On a use payload it is how many exist right now. - `twitter_credits` integer: Monthly X (Twitter) credits. X bills per use: 15 per post, 200 if the text contains a link, 15 per deletion, 1 per stat read, 1 per timeline item. The pool resets on the 1st of each calendar month and does not roll over. - `ai_credits` integer: Monthly AI credits (1 credit = $0.001 of provider cost): 15 per plan orchestration pass, 2 per generated text, 70 per generated image. Resets monthly and does not roll over. A client using its own provider key (BYOK) does not consume them in that scope. - `actual_asigned` PlanData: The resources a plan grants. On a client it is what was contracted; on an organization, the slice of it that was assigned. The sum across all the organizations of a client can never exceed what the client has contracted. Users are NOT here: every plan has unlimited users, so they are neither charged nor split between organizations. They are still counted, in `PlanUseData.users`. There are no `artificial_inteligence`, `whatsapp` or `stats` flags either: statistics and WhatsApp are on every plan, and what gates AI is `ai_credits` — a plan with credits has AI, and Free has zero. - `accounts` integer, required: Social accounts that may be connected. - `space` number, required: Storage, in GB. - `integrations` integer, required: Connections to a third-party tool material is pulled from (Google Drive, an RSS feed). Not the same thing as an app: an app is API access, and it has its own allowance in `apps`. - `apps` integer: Apps this plan allows: 1 on Free, 2 on Basic, 5 on Pro, 10 on Custom. Each one is a `client_id` with a secret, so each one is a key to the whole public API — which every plan has, Free included. Unlike accounts or storage this is NOT split between organizations: an app belongs to the client. On a use payload it is how many exist right now. - `twitter_credits` integer: Monthly X (Twitter) credits. X bills per use: 15 per post, 200 if the text contains a link, 15 per deletion, 1 per stat read, 1 per timeline item. The pool resets on the 1st of each calendar month and does not roll over. - `ai_credits` integer: Monthly AI credits (1 credit = $0.001 of provider cost): 15 per plan orchestration pass, 2 per generated text, 70 per generated image. Resets monthly and does not roll over. A client using its own provider key (BYOK) does not consume them in that scope. - `ai_context` AiContext: Brand context for AI generation. Every field is optional; the ones you fill in are what the model is told about the business. - `brand_name` string: Commercial name, when it differs from the organization's. - `description` string: What the organization does. - `sector` string - `audience` string: Who the content is aimed at. - `value_proposition` string - `website` string - `shop_url` string - `blog_url` string - `social_urls` string[]: Social profiles or other reference links. - `default_tone` string: Default tone. A tone set on the plan itself wins over this one. - `keywords` string[]: Recurring keywords and hashtags. - `products` string: Products or services that may be promoted. - `avoid` string: Topics, expressions or competitors that must never appear. - `notes` string: Anything else the model should know. - `stats_settings` StatsSettings: Statistics collection settings. Only `auto_refresh_twitter` is read; any other key is ignored. - `auto_refresh_twitter` boolean: Whether the background job refreshes X (Twitter) statistics automatically. Every other network is free and always refreshed; X charges 1 credit per read, so this is the one setting that makes the robot spend the client's credits. Anything other than an explicit `false` is treated as `true`. - `social_credentials` object: The organization's own application credentials, by network. A network that is absent is not configured, and then it does not even appear as connectable. - `discord` SocialCredentials: What can be read back about an organization's own application. The secrets are not here and never will be. - `client_id` string - `application_name` string: The application's name, as Discord returned it when the credentials were validated. - `verified_date` string, date-time: When the credentials were last validated against Discord. - `has_client_secret` boolean: Whether a secret is stored. Never the secret. - `has_bot_token` boolean: Whether a bot token is stored. Never the token. - `total` integer, required: Organizations this client has, ignoring the pagination. - `total` integer, required: Clients the caller can see. ## Other responses - `400`: The request failed. The body carries the PlanVortex error code in `code`: | Code | Meaning | | --- | --- | | `521` | Invalid client. The identifier is invalid or doesn't exist | - `500`: Unhandled error by the server --- [API](https://skmtc.dev/planvortex/apis/planvortex-api.md) · [All operations](https://skmtc.dev/planvortex/apis/planvortex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/planvortex/apis/planvortex-api/revisions/abedbbc1cd52?raw)