Base URL & versions#

All Cloud API requests go to one base URL:

bash

https://api.kenari.dev

Everything after the host follows Meta's Graph API path format, including the version.

Path shape#

The proxy accepts two path shapes:

Shape	Example
`/{version}/{id}`	`GET /v23.0/123456789012345`
`/{version}/{id}/{edge}`	`POST /v23.0/123456789012345/messages`

{version} is a Graph API version written as v + a number + .0, such as v23.0.
{id} is a phone number ID, a WABA ID or a media ID that belongs to your account.
{edge} is one of the supported edges: messages, media, message_templates or whatsapp_business_profile.

The methods are GET, POST, PUT and DELETE. Deeper paths, other edges and other methods return 404 with KenariRoutingException, as does any ID that doesn't belong to your account. See Supported endpoints for which method and edge go with which kind of ID.

Query strings are forwarded to Meta, so parameters such as fields or limit work as they do on Meta's API.

bash

curl "https://api.kenari.dev/v23.0/$WABA_ID/message_templates?limit=10" \  -H "Authorization: Bearer $KENARI_API_KEY"

Graph API versions#

kenari doesn't choose a Graph API version for you. The version in your path is the version kenari forwards to Meta: a request to /v23.0/{id}/messages is sent to https://graph.facebook.com/v23.0/{id}/messages.

This means:

You control upgrades. kenari never rewrites or upgrades the version in your request. Move to a newer version on your own schedule by changing the path.
Payload differences between versions are Meta's. Check Meta's changelog before you change the version, just as you would when calling Meta directly.
Retired versions fail at Meta. When Meta retires a version, requests that still use it get Meta's error response, passed through unchanged.

When Meta schedules the retirement of a Graph version, we'll note it in the changelog ahead of the cut-off.

Response headers#

Meta's response status and body pass through unchanged. kenari passes on these Meta headers:

Header	From
`Content-Type`, `Content-Length`, `Content-Disposition`	Meta
`x-fb-trace-id`, `x-fb-rev`	Meta
`x-business-use-case-usage`, `x-app-usage`	Meta

And adds its own:

Header	Meaning
`X-Kenari-Request-Id`	kenari's ID for this request. Quote it when you contact support.
`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`	Your current rate-limit bucket. See Rate limits.
`Retry-After`	Seconds to wait, sent with a `429`.

Timeouts and body size#

Message sends and most other calls wait up to 30 seconds for Meta. Media uploads and downloads wait up to 120 seconds. When Meta doesn't answer in time, kenari returns 503 with KenariUpstreamException. If Meta can't be reached at all, it returns 502 with the same type.
Request bodies are limited to 100 MB. Larger bodies get 413 with KenariPayloadTooLargeException.