Skip to main content
POST
/
v1
/
api-keys
Create a new API key
curl --request POST \
  --url https://api.waterfall.io/v1/api-keys \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "notes": "team-a",
  "per_interval": 30
}
'
{
  "api_key": "ad18e456-0dd7-45e1-b094-43a0361aedfa",
  "active": true,
  "notes": "team-a",
  "master": false,
  "per_interval": 30,
  "interval_seconds": 60
}
Requires your master API key in the x-api-key header.

​
What this endpoint does

Creates a new sub-key under your account. Use sub-keys to isolate usage by team, environment, or integration — each key has its own rate limit and can be activated or deactivated independently.

​
Rate limit constraint

The per_interval of any sub-key cannot exceed the per_interval of your master key. If omitted, it defaults to 30 requests per 60 seconds.
If your account does not have a master key, this endpoint returns 404. Contact your account manager to enable key management.

Authorizations

​
x-api-key
string
header
required

To access the API, provide your API key in x-api-key.

Body

application/json

Create sub-key payload. notes is required. per_interval is optional; if omitted, the current implementation defaults to 50. The value cannot exceed the master key's per_interval.

Request payload to create a new sub API key.

​
notes
string
required

Notes associated with the API key.

Required string length: 1 - 250
Example:

"My API key"

​
per_interval
integer<int32>
default:50

Optional per-interval request limit for the new sub-key. If omitted, the current implementation defaults to 50. It cannot exceed the master key's per_interval.

Required range: x >= 1

Response

API key succesfully created.

API key record including metadata and rate-limit settings.

​
api_key
string<uuid>
required

A UUID.

Example:

"7d44db58-5de3-4e92-a2fb-8325d12c2e8b"

​
active
boolean | null
required

True if the API key is active, false otherwise.

Example:

true

​
notes
string
required

Notes associated with the API key.

Required string length: 1 - 250
Example:

"My API key"

​
master
boolean
required

True for the master key, false for sub-keys.

Example:

false

​
per_interval
integer<int32>
required

Requests allowed per interval.

Example:

30

​
interval_seconds
integer<int32> | null
required

Interval duration in seconds (always 60).

Example:

60