Caddi
Sign inSign up

API

A public REST API with the same scope as the CLI — V1.5 on the roadmap. Available today: the form submission endpoint and inbound/outbound webhooks.

Available today

  • POST /api/f/[id] — form submission endpoint. JSON or multipart.
  • Webhooks (outbound) — request.*, form.*, deploy.*. Configure at Settings → Webhooks.

Coming in V1.5

A full REST API mirroring the CLI surface. Project CRUD, env-var management, deploy triggers, requests inbox, audit-log reads. Token-based auth using the same CLI tokens.

  • GET /v1/projects — list projects in an agency.
  • POST /v1/projects — scaffold a project.
  • POST /v1/projects/:id/promote — open a promotion PR.
  • GET /v1/requests — list requests, filter and paginate.
  • POST /v1/requests/:id/reply — reply to a request.
  • GET /v1/audit-log — paginated event stream.
The public REST API is targeted for the V1.5 release. Until then, the CLI’s --json flag is the supported way to script Caddi from external systems.

Webhook signing

Every outbound webhook includes an HMAC-SHA256 signature header:

bash
# Header
x-caddi-signature: t=1717000000,v1=4f8a2c...

# Verify
const expected = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(`${timestamp}.${rawBody}`)
  .digest('hex');

Rate limits

  • Form submissions: 30 / 5 minutes / IP (configurable per form).
  • CLI: 600 / minute / token.
  • Webhook delivery retries: 5 attempts with exponential backoff over 24h.

Next

POST /api/f/[id] →