Versioning
v1 only ever grows. New endpoints, optional parameters and response fields arrive without notice. A breaking change ships as /v2, next to v1.
The version is in the path: https://api.koast.ai/v1. Webhook payloads carry it too, as "apiVersion": "v1".
What can change inside v1
Only additive changes:
- New endpoints.
- New optional query parameters and body fields.
- New fields in responses and in webhook
data. - New error codes.
- New webhook event types. An endpoint only receives the types it subscribed to.
What never changes inside v1
- An endpoint or method being removed.
- A response field being removed or changing type.
- A type being narrowed, or a maximum being lowered.
- A previously optional input becoming required.
- An enum value being removed.
Every Koast release checks the generated OpenAPI spec against the published v1 spec, and fails on any of these. A change that needs one ships as /v2, alongside /v1.
Write tolerant clients
- Ignore response fields you don't know.
- Treat an unknown error
codeby its HTTP status. See Errors. - Don't fail on an unknown enum value in a response. Log it and carry on.
- Ignore webhook event types you didn't expect, and answer
2xxanyway.
What's new
See the Changelog. The live spec is always at https://api.koast.ai/v1/openapi.json.
Metrics freshness
Metrics are read live from Meta and Whop. A read can come from a short cache, up to 5 minutes old for today and up to 1 hour for past days, and asOf tells you when it was read.
Webhooks
Get an HTTPS POST when a launch finishes, an ad is reviewed, delivery changes or a day's spend closes. Verify every delivery with the Standard Webhooks libraries.