> ## Documentation Index > Fetch the complete documentation index at: https://docs.cocoondata.com/llms.txt > Use this file to discover all available pages before exploring further. # /api/v1/organisations/{orgGroupId}/plans ## URL structure ```text theme={null} https://access-service.xy-company.com/api/v1/organisations/{orgGroupId}/plans ``` where `{orgGroupId}` is the ID of an organisation. ## Supported methods and overview * `POST` - adds a new [plan](/CS1.2/admin-org/managing-users-storage-quotas-through-plans.md) to an organisation (specified by `orgGroupId`). * `GET` - retrieves a list of information for all plans configured within an organisation (specified by `orgGroupId`). > [!NOTE] > > The `GET` method takes no parameters. ## Detailed description This API endpoint serves a number of purposes: * Adds a new plan to an organisation (specified by `orgGroupId`). \ **Note:** It is necessary for an organisation to have at least one plan to grant the [Originator](/CS1.2/admin-org/administering-users-within-an-organisation.md#originator-role) role to Cocoon Data user accounts within this organisation - see the [\/api/v1/organisations/\{orgGroupId}/users](/CS1.2/api/access-service-api-v1-organisations-orggroupid-users.md) API endpoint for more information. * Retrieves a list of information for all plans configured within an organisation (specified by `orgGroupId`). ## Supported roles and conditions This API endpoint supports requests utilising Cocoon Data user accounts with the following [roles](/CS1.2/admin-org/administering-users-within-an-organisation.md#an-organisation-users-roles) (as described in the [Organisation Administrator's Guide](/CS1.2/admin-org.md)) and conditions: * [Organisation administrator](/CS1.2/admin-org/administering-users-within-an-organisation.md#organisation-administrator-role) - when this user is a member of the organisation specified by `{orgGroupId}` in the request's URL. The Cocoon Data Platform's resources available to a Cocoon Data user meeting the criteria above is determined by the access token submitted in the [header](/CS1.2/api/access-service-api-v1-organisations-orggroupid-plans.md#access-service-api-v1-organisations-orggroupid-plans-required-headers) of requests to this endpoint. ## Required headers The appropriate access token as the `Bearer` token: * `Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...` The following header is required if the body of the request has a JSON object: * `Content-Type: application/json` ## Required POST-request parameters The following required parameters must be sent in the **body** of the POST request, each as individual members of a **JSON object**: * **name** - The name of the plan to be added to the organisation specified by `{orgGroupId}` in the request's URL. * **description** - The description for this new plan. * **quota** - The quota (in MiB) to set for this new plan. \ **Note:** A *MiB* is a [mebibyte](http://physics.nist.gov/cuu/Units/binary.html), where one MiB = 1 x 1024 x 1024 bytes = 1048576 bytes. \ **Example (request):** ```json theme={null} { "name": "Temporary Staff Originators", "description": "Temporary staff members with the Originator role.", "quota": 4096 } ``` ## Optional POST-request parameters The following optional parameters can also be sent in the **body** of the POST request, each as individual members of the **JSON object** that includes the [Required POST-request parameters](/CS1.2/api/access-service-api-v1-organisations-orggroupid-plans.md#access-service-api-v1-organisations-orggroupid-plans-required-post-request-parameters) above: * **default** - A boolean value determining whether (`true`) or not (`false`) the new plan being added to the organisation (specified by `{orgGroupId}` in the URL) will be flagged as the **default** plan for this organisation. \ **Example (request):** ```json theme={null} { "name": "Temporary Staff Originators", "description": "Temporary staff members with the Originator role.", "quota": 4096, "default": true } ``` ## Optional GET-request parameters The following optional parameters can be sent in the **URL** of the GET request: * **limit** - An integer value from `0` to `100`, representing the maximum number of items to be returned in the response, where an individual item is information about a plan configured in the organisation (specified by `{orgGroupId}` in the request's URL). If this parameter is omitted, then its value is `0` by default, which does not apply restrictions to the number of items returned in the response. * **offset** - A value representing the count order of all retrievable items (i.e. plans in the organisation specified by `{orgGroupId}` in the URL) returned in the response. Calls to this API endpoint may amount to potentially large numbers of items being returned from the Cocoon Data Platform. Since the order of these items in the response could differ significantly, based on the values of the **orderBy** and **sortBy** parameters below, this **offset** parameter provides pagination for items returned in responses, allowing items to be retrieved from any count greater than `0` (i.e. the first item returned in a response). If this parameter is omitted, then its value is `0` by default. * **orderBy** - An enumeration (enum) value representing the order in which items (i.e. plans in the organisation specified by `{orgGroupId}` in the URL) are returned in the response. This parameter orders items according to the value of the **sortBy** parameter specified below. Ordering items can be in either ascending alphanumeric order (by specifying the value `ASC` for this parameter) or descending order (by specifying the value `DESC`). If this parameter is omitted, then its value is `ASC` by default. * **sortBy** - A value representing the field (i.e. member) of a retrieved item by which items (i.e. plans in the organisation specified by `{orgGroupId}` in the URL) returned in the response will be sorted. Valid field values for this parameter include: * `name` - the name of the plan and * `description` - the description of the plan. * `quota` - the description of the plan. **Example (request):** ```text theme={null} https://access-service.xy-company.com/api/v1/organisations/760756644367081472/plans?limit=10 ``` > [!NOTE] > > Due to a bug, if the **limit** URL parameter above is not specified with a value > `0`, then none of the other parameters submitted in the `GET` request have any impact on items returned in the response. ## Returns If the request succeeded, then an HTTP response status `200 OK` is returned. For successful requests only, a JSON-formatted response containing the following members is also returned: * **items** ( *from GET requests only* ) - An array containing information about all existing plans configured in the organisation (specified by `{orgGroupId}` in the request's URL), where these groups have been filtered by any [parameters](/CS1.2/api/access-service-api-v1-organisations-orggroupid-plans.md#access-service-api-v1-organisations-orggroupid-plans-optional-get-request-parameters) submitted in the request. Each element of this array contains information about one of these plans (represented as an object containing the following members unless otherwise stated). * **id** - The ID of the (new) plan. * **name** - The name of the (new) plan. * **description** - The description of the (new) plan. * **quota** - The current quota of the plan (in MiB). * **default** - A boolean value indicating whether (`true`) or not (`false`) this plan is flagged as the **default** plan for this organisation. * **count** ( *from GET requests only when specifying a **limit** parameter value > 0* ) - The total number of items (i.e. plans configured in the organisation specified by `{orgGroupId}` in the request's URL) that can be returned in the response. * **offset** ( *from GET requests only when specifying a **limit** parameter value > 0* ) - The value of the **offset** which had been used in the request to this API endpoint. \ **Example (response):** ```json theme={null} { "items": [{ "id": "760757068528656384", "name": "Staff Originators", "description": "Staff members with the Originator role.", "quota": 10240, "default": true }, { "id": "767973799974182912", "name": "Temporary Staff Originators", "description": "Temporary staff members with the Originator role.", "quota": 4096, "default": false }], "count": "2", "offset": "0" } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.