API Documentation

Authentication

All API calls require a Bearer token. Generate keys in Admin → Developer. Scope keys to read:deals, read:proposals, webhooks:manage, etc.

curl -H "Authorization: Bearer fsk_..." \
  https://api.flowshark.ai/api/public/v1/deals

Base URL

https://api.flowshark.ai/api/public/v1

Scopes

• read:deals / write:deals
• read:leads / write:leads
• read:clients / write:clients
• read:proposals / write:proposals
• read:invoices / write:invoices
• webhooks:manage

write:* scopes require an api_access plan tier above read_only. Read-only keys reject any write: / delete: / admin: scope at creation time.

Endpoints (live today)

• GET /health — auth + rate-limit echo.
• GET /scopes — scope catalog.
• GET /events — webhook event-type catalog.
• GET /deals, GET /leads, GET /clients, GET /proposals, GET /invoices — cursor-paginated list (max limit=200).
• POST /webhooks — subscribe to events. webhooks:manage scope required.

Project endpoints are reserved and currently return 501.

Rate Limits

Rate limits are per API key, not per plan tier. Default 60 requests/minute per key, configurable up to 6000/min at key creation. The plan controls how many keys you can mint and whether write:* is allowed; once a key exists, its limit lives on the key itself.

Responses include X-RateLimit-Limit and X-RateLimit-Remaining. Exceed the limit and you get 429 with Retry-After: 60.

Webhooks

Subscribe to events like proposal.sent, invoice.paid, deal.stage_changed, lead.scored. Globs supported: * or deal.*. Each delivery is HMAC-SHA256-signed with your subscription secret — verify the X-Flowshark-Signature header before trusting the payload.

Webhook subscription count is capped per plan (webhooks_per_month limit). Free tier has no webhooks.

OpenAPI Schema

Internal admin schema served at https://api.flowshark.ai/api/v1/openapi.json. A public-API-only schema is on the roadmap.

SDKs

No official SDKs yet. The OpenAPI schema above generates idiomatic clients via openapi-generator in any language.