> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.hoop.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Creates a batch of resource plans > Validates provisioning plans for a batch of resources by computing the diff between the desired and current role state for each resource. Each item is session-audited and receives its own plan ID (SID) that can be referenced when applying. All items are processed concurrently and the response is returned once all have completed. Per-item failures are embedded in the results with status "failed" rather than returned as HTTP errors. ## OpenAPI ````yaml https://use.hoop.dev/api/openapiv3.json post /resources/plan openapi: 3.0.3 info: contact: email: help@hoop.dev name: Help url: https://help.hoop.dev description: >- Hoop.dev is an access gateway for databases and servers with an API for packet manipulation license: name: MIT url: https://opensource.org/license/mit termsOfService: https://hoop.dev/docs/legal/tos title: Hoop Api version: 1.94.0 servers: - url: https://use.hoop.dev/api security: [] tags: - description: > Hoop implements Oauth2 and OIDC protocol to authenticate users in the system. To obtain a valid access token users need to authenticate in their own identity provider which is generated as a JSON response to the endpoint `http(s)://use.hoop.dev/api/login`. The identity provider them redirects the user to the callback endpoint containing the access token. The recommended approach of obtaining an access token is by visiting the Webapp main's page or using the **Hoop command line**. Example: ```sh hoop config create --api-url https://use.hoop.dev # save the token after authenticating at $HOME/.hoop/config.toml hoop login # show token information hoop config view --raw ``` With an access token you could use any HTTP client to interact with the documented endpoints. The token must be sent through the `Authorization` header. Example: ```sh # obtain the current configuration of the server curl https://use.hoop.dev/api/serverinfo -H "Authorization: Bearer $ACCESS_TOKEN" ``` name: Authentication - description: > Users are active and assigned to the default organization when they signup. A user could be set to an inactive state preventing it from accessing the platform, however it’s recommended to manage the state of users in the identity provider. - The `sub` claim is used as the main identifier of the user in the platform. - The profile of the user is derived from the id_token claims `email` and `name`. When a user authenticates for the first time, it performs an automatic signup that persist the profile claims along with it’s unique identifier. ​ ### Groups Groups allows defining who may access or interact with certain resources. - For connection resources it’s possible to define which groups has access to a specific connection, this is enforced when the Access Control feature is enabled. - For review resources, it’s possible to define which groups are allowed to approve an execution, this is enforced when the Review feature is enabled. > This resource could be managed manually via Webapp or propagated by the identity provider via ID Token. In this mode, groups are sync when a user performs a login. ### Roles - The `admin` group is a special role that grants full access to all resources This role should be granted to users that are responsible for managing the Gateway. All other users are regular, meaning that they can access their own resources and interact with connections. name: User Management - name: Machine Identities - description: Routes used to manage and obtain information about the runtime server. name: Server Management - description: Features available in the gateway. See also **Plugin** resources. name: Features - description: >- Proxy manager endpoints controls how clients connect via gRPC in the gateway. These endpoints are meant to be used when a client is initialized via `hoop proxy-manager`. name: Proxy Manager - name: Connections - name: Agents - name: Runbooks - name: Guard Rails - name: Reviews - name: Sessions - name: Organization Management - name: Reports - description: > Security audit log API. Only users in the **admin** group can access these endpoints. Audit log entries record security-relevant events (who performed an action, when, on which resource, and whether it succeeded). Use the list endpoint with filters to query by actor, resource type, action, outcome, or date range. Results are paginated and ordered by `created_at` descending. name: Audit Logs paths: /resources/plan: post: tags: - Resources summary: Creates a batch of resource plans description: >- Validates provisioning plans for a batch of resources by computing the diff between the desired and current role state for each resource. Each item is session-audited and receives its own plan ID (SID) that can be referenced when applying. All items are processed concurrently and the response is returned once all have completed. Per-item failures are embedded in the results with status "failed" rather than returned as HTTP errors. requestBody: content: application/json: schema: $ref: '#/components/schemas/openapi.ResourcePlanRequest' description: The request body required: true x-originalParamName: request responses: '200': content: application/json: schema: $ref: '#/components/schemas/openapi.ResourcePlanResponse' description: OK '400': content: application/json: schema: $ref: '#/components/schemas/openapi.HTTPError' description: Bad Request components: schemas: openapi.ResourcePlanRequest: properties: items: description: The list of plan items to process items: $ref: '#/components/schemas/openapi.ResourcePlanItem' minItems: 1 type: array required: - items type: object openapi.ResourcePlanResponse: properties: results: description: The list of plan results items: $ref: '#/components/schemas/openapi.ResourcePlanResult' type: array type: object openapi.HTTPError: properties: message: example: the error description type: string type: object openapi.ResourcePlanItem: properties: privileges: description: >- The list of privileges to grant on all tables in each scope. Supported values: SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES, TRIGGER, CREATE, EXECUTE. example: - SELECT - INSERT items: type: string type: array resource_name: description: >- The resource name to plan provisioning for. Required for batch requests. example: my-postgres type: string role: description: >- A short label used to derive the generated postgres role name (e.g. "ro", "rw", "analyst"). The actual role created in postgres is a deterministic slug of the form hoopdev___. example: ro type: string rotate_password: description: >- When true, rotates the role's password on this plan run. Only takes effect if the role already exists; new roles always receive a freshly generated password regardless of this flag. example: false type: boolean scopes: description: >- The list of databases and schemas to apply privileges to, formatted as "database" or "database.schema". If the schema is omitted, privileges are applied to the public schema of that database. example: - mydb - otherdb.public items: type: string type: array source_role: description: >- An existing postgres role whose privileges the new role will inherit via membership. Only relevant when type is "external"; ignored for "managed". example: pg_read_all_data type: string type: description: >- Role management mode. "managed" creates and fully owns the postgres role (password managed by hoop). "external" attaches the role as a member of an existing parent role specified by source_role. enum: - managed - external example: managed type: string required: - privileges - role - scopes - type type: object openapi.ResourcePlanResult: properties: message: description: Error message populated when status is "failed"; empty on success example: 'failed retrieving resource: connection refused' type: string resource_name: description: The resource name this plan result is for example: my-postgres type: string role: description: >- The generated postgres role name derived from the resource name and role label (format: hoopdev___<8-char-hash>). example: hoopdev_my_postgres_ro_ab3c1f7e type: string sid: description: The session ID for tracking and auditing this plan execution example: 5701046A-7B7A-4A78-ABB0-A24C95E6FE54 format: uuid type: string status: description: Status of the plan execution enum: - success - failed example: success type: string type: object ````