API

WoolKey can generate passwords and passphrases for your scripts, tools, and AI agents — the same generator the website uses, reachable over HTTP.

Do I need an API key?

How to get a key

Keys are issued individually, on request. You get your own rather than a shared one, so usage stays traceable to a single key and any one key can be revoked without disturbing anybody else.

Quick start

Three steps from nothing to a generated password.

1. Check the API is up

   No key needed for this one.

   Copy

   curl https://api.woolkey.com/health

   You should get back {"status":"ok", ...}.

2. Put your key in a variable

   So it never ends up in your shell history or pasted into a chat.

   Copy

   export WOOLKEY_KEY="your-key-here"

3. Generate a password

   Copy

   curl -X POST https://api.woolkey.com/generate \
     -H "Content-Type: application/json" \
     -H "X-Api-Key: $WOOLKEY_KEY" \
     -d '{"mode":"password","options":{"length":24,"includeSymbols":true}}'

   The password comes back in the value field.

Endpoints

Base URL: https://api.woolkey.com

Making a request

Send POST to /generate with a JSON body. Only mode is required — leave anything else out and a sensible default is used.

Options for mode: "password"

Options for mode: "passphrase"

What you get back

{
  "mode": "password",
  "count": 1,
  "value": "EXAMPLE-your-password-appears-here",
  "entropy": { "bits": 149.95, "label": "Excellent", "level": 4 },
  "metadata": { "entropyMode": "system", "poolSize": 76, "length": 24 },
  "results": [ { "value": "...", "entropy": {...}, "metadata": {...} } ]
}

• value — the generated password or passphrase. This is the part you want.
• entropy.bits — how hard it is to guess. Higher is better.
• entropy.label — the same number in words: Weak, Fair, Strong, Very strong, Excellent.
• results — one entry per credential. When you ask for several, they are all here.

If you only ever ask for one credential, read value and ignore results — the top-level fields always mirror the first result.

Generating several at once

Set count to get a batch in a single request, which also uses only one of your rate-limit slots instead of twenty.

curl -X POST https://api.woolkey.com/generate \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $WOOLKEY_KEY" \
  -d '{"mode":"password","count":5,"options":{"length":32}}'

More examples

Passphrase

curl -X POST https://api.woolkey.com/generate \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $WOOLKEY_KEY" \
  -d '{"mode":"passphrase","options":{"wordCount":6,"capitalize":true}}'

Gives you something like Eagle-Newer-Shock-Folio-Depot-Taste.

JavaScript

const res = await fetch('https://api.woolkey.com/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': process.env.WOOLKEY_KEY,
  },
  body: JSON.stringify({
    mode: 'password',
    options: { length: 24, includeSymbols: true },
  }),
});

if (!res.ok) throw new Error((await res.json()).error);
const { value } = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.woolkey.com/generate",
    headers={"X-Api-Key": os.environ["WOOLKEY_KEY"]},
    json={"mode": "password", "options": {"length": 24, "includeSymbols": True}},
    timeout=10,
)
res.raise_for_status()
password = res.json()["value"]

Postman

Don't build the requests by hand — import the ready-made collection. It arrives with every request filled in, documented, and with tests that check the responses.

Fastest: import by link

In Postman: Import → Link → paste this → Continue.

https://api.woolkey.com/woolkey.postman_collection.json

Then set your key: open the collection → Variables → paste it into apiKey under Current value. That column stays on your machine, so the key is not included if you later export or share the collection.

That's it. Hit Send on 1. Health check to confirm it works, then 3. Generate a password.

Or download the files

Drag either file onto the Postman window to import it.

Both files download straight from this site — no Postman account, and nothing published to a public workspace.

What's in the collection

By hand

If you would rather set it up yourself: method POST, URL https://api.woolkey.com/generate, headers Content-Type: application/json and X-Api-Key: your-key, then body → raw → JSON with any of the bodies above. Importing openapi.json the same way works too, though it produces bare requests with no tests or examples.

Connecting an AI agent

The API is designed so an agent can work it out on its own. Point it at the description endpoint and it learns every mode, option, default, and limit without you writing a schema:

curl https://api.woolkey.com/generate

For a tool definition, hand the agent the POST /generate schema from openapi.json. Then:

• Keep the key in an environment variable, not in the tool definition itself.
• Tell the agent to treat value as a secret — not to print it, log it, or write it into a transcript.
• Read the error and field fields on a failure; they say exactly what to fix.

When something goes wrong

Errors always come back as JSON, and name the field at fault where there is one:

{ "error": "options.length must be between 8 and 128",
  "status": 400,
  "field": "options.length" }

Rate limits

20 requests per minute from one IP address. Every reply tells you where you stand:

• X-RateLimit-Remaining — requests left in this minute
• X-RateLimit-Reset — seconds until the count resets
• Retry-After — on a 429, how long to wait

Need a lot of credentials? Use count — one request for twenty passwords instead of twenty requests.

What happens to what you generate

Requests are served over HTTPS and responses are marked no-store, so browsers and proxies are told not to keep a copy either. See Security for the full picture.

In-browser alternative

If your agent drives a real browser rather than speaking HTTP, this page's generator is available directly on the WoolKey home page as window.WoolKeyAPI — no key, no network request, nothing leaves the browser.

// Run this on the WoolKey home page
const result = window.WoolKeyAPI.generate({
  mode: 'password',
  count: 3,
  options: { length: 24, includeSymbols: true },
});

if (!result.ok) throw new Error(result.error);
result.data.results.map(r => r.value);

It takes the same options as the HTTP endpoint and returns the same numbers, so you can swap between the two. window.WoolKeyAPI.describe() lists everything available, and generate() returns { ok: false, error } instead of throwing, which is easier to handle from an automation script.

Reference

• openapi.json — full machine-readable specification
• api/generate — live description of this server's current limits
• Postman collection — six ready-made requests
• Postman environment — optional key holder