API keys

Every Guilde feature available in the UI is also available over a REST API. API keys are how your code authenticates.

For the full surface: Swagger UI. Below covers managing keys and the conventions you'll meet.

Creating a key

Settings → API keys → Create key. Give it a name (where will you use it — "Local dev", "GitHub Actions", "Zapier zap") and an optional expiration. The full key is shown once; copy it now, you can't see it again.

Keys use the gld_ prefix:

gld_a1b2c3d4e5f6...

If you lose a key, rotate it (delete + create new). Compromised keys can be revoked from the same page; revocation is immediate.

Using a key

Pass as a Bearer token:

curl https://api.guilde.work/guilde/api/v1/guilds \
  -H "Authorization: Bearer gld_your_key"

Or with the SDK:

import { GuildeClient } from "@guilde/sdk"

const guilde = new GuildeClient({
  apiKey: process.env.GUILDE_API_KEY,
})

const guilds = await guilde.guilds.list()

API keys are user-scoped — they have the same access the user who created them has. There's no per-key scoping yet (planned).

Common uses

• Webhook listeners — your service receives a webhook from a third party, calls Guilde to enqueue a work item or post a message in an operator conversation.
• CI / CD — a deploy pipeline asks an operator to draft release notes or run a smoke-test routine.
• Zapier / Make — connect Guilde to systems Guilde doesn't have a native connector for (using the API as a generic webhook target).
• Scripts — quick automations: bulk-import contacts, batch-create work items from a CSV, etc.

Rate limits

Hit a limit, you get HTTP 429 with a Retry-After header. Bursts are allowed — the limit is a token bucket, not a hard rolling window.

What's next

• Swagger UI — every endpoint
• Members — humans inside the guild