Skip to main content
POST
/
resources
/
{name}
/
plan
Creates a resource plan
curl --request POST \
  --url https://use.hoop.dev/api/resources/{name}/plan \
  --header 'Content-Type: application/json' \
  --data '
{
  "privileges": [
    "SELECT",
    "INSERT"
  ],
  "role": "ro",
  "scopes": [
    "mydb",
    "otherdb.public"
  ],
  "type": "managed",
  "resource_name": "my-postgres",
  "rotate_password": false,
  "source_role": "pg_read_all_data"
}
'
{
  "message": "failed retrieving resource: connection refused",
  "resource_name": "my-postgres",
  "role": "hoopdev_my_postgres_ro_ab3c1f7e",
  "sid": "5701046A-7B7A-4A78-ABB0-A24C95E6FE54",
  "status": "success"
}

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.

Path Parameters

​
name
string
required

The resource name

Body

application/json

The request body

​
privileges
string[]
required

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"]
​
role
string
required

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"

​
scopes
string[]
required

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"]
​
type
enum<string>
required

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.

Available options:
managed,
external
Example:

"managed"

​
resource_name
string

The resource name to plan provisioning for. Required for batch requests.

Example:

"my-postgres"

​
rotate_password
boolean

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

​
source_role
string

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"

Response

OK

​
message
string

Error message populated when status is "failed"; empty on success

Example:

"failed retrieving resource: connection refused"

​
resource_name
string

The resource name this plan result is for

Example:

"my-postgres"

​
role
string

The generated postgres role name derived from the resource name and role label (format: hoopdev_<8-char-hash>).

Example:

"hoopdev_my_postgres_ro_ab3c1f7e"

​
sid
string<uuid>

The session ID for tracking and auditing this plan execution

Example:

"5701046A-7B7A-4A78-ABB0-A24C95E6FE54"

​
status
enum<string>

Status of the plan execution

Available options:
success,
failed
Example:

"success"