Events › Open a link in its app
Events
Open a link in its app
POST/api/{ORG}/events/openPermalink
What an app sends when one of its links opened it (Universal Links, App Links): url, the link as the app was handed it. The edge decides the visit as any other and counts its click; the answer is { open: "app", path, brvClick } to stay in the app at path, or { open: "browser", url } to hand the visit to the browser (an expired, disabled, password-protected or otherwise unopenable link). From an app’s publishable key, or a secret key; an app’s key answers 404 for a link whose deep link opens another app, or on a domain not picked for its app.
- Permission
- Integrations · create
- Plan
- Plans that include the API: Pricing
- Retry
- Safe with an
Idempotency-Key
Example request
curl -X POST "https://console.brevily.com/api/NORTHWIND/events/open" \ -H "x-api-key: brv_ak_7Fq2Lw9xK3" \ -H "x-api-secret: $BREVILY_SECRET" \ -H "Idempotency-Key: 4f9c1e2a-autumn" \ -H "Content-Type: application/json" \ -d '{ "url": "https://www.example.com/sale/autumn", "key": "example" }'const res = await fetch("https://console.brevily.com/api/NORTHWIND/events/open", { method: "POST", headers: { "x-api-key": "brv_ak_7Fq2Lw9xK3", "x-api-secret": process.env.BREVILY_SECRET, "Idempotency-Key": "4f9c1e2a-autumn", "Content-Type": "application/json", }, body: JSON.stringify({ "url": "https://www.example.com/sale/autumn", "key": "example" }),});const answer = await res.json();Example answer
{ "open": "app", "path": "example", "brvClick": "example", "url": "https://www.example.com/sale/autumn"}{ "code": "VALIDATION_FAILED", "message": "Check the form. url: Not a value this field takes.", "details": { "fields": { "url": "Not a value this field takes." } }, "requestId": "18188559082372202519"}Made-up values. Send your own Idempotency-Key, one per change.
PathPermalink
| Name | Type | Required | Description | Allowed values |
|---|---|---|---|---|
ORG | string | required | Your organisation’s code. | 3 to 20 characters |
HeadersPermalink
| Name | Type | Required | Description | Allowed values |
|---|---|---|---|---|
user-agent | string | optional | — |
BodyPermalink
JSON. An unknown field is refused with a 400 naming it.
| Name | Type | Required | Description | Allowed values |
|---|---|---|---|---|
url | string | required | The link the app was opened with, as it was handed it. | — |
key | string | optional | The app’s publishable key, when it cannot travel in the x-brevily-key header. | — |
AnswerPermalink
OpenAnswer
| Name | Type | Description | Allowed values |
|---|---|---|---|
open | string | app: show path in the app. browser: open url in the browser. | app, browser |
path | string | The path inside the app (the link’s deep link, with the visit’s query); with app only. | — |
brvClick | string | The visit’s click as <click id>.<link id>: what the app reports install and its events with; null when no click was counted. With app only. | or null |
url | string | Where the browser goes; with browser only. | — |
ErrorsPermalink
| Status | Code | When |
|---|---|---|
| 400 | VALIDATION_FAILED |
A field, a parameter or the body is wrong; details.fields says which. |
| 400 | IDEMPOTENCY_KEY_INVALID |
The Idempotency-Key is longer than 255 characters. |
| 401 | UNAUTHENTICATED |
No key, a key that does not match, or one expired or revoked. |
| 403 | ACCESS_DENIED |
The key lacks Integrations · create, or the organisation’s plan does not include it. |
| 404 | NOT_FOUND |
No organisation with that code for this key, or no such record in it. |
| 409 | CONFLICT |
|
| 409 | IDEMPOTENCY_IN_FLIGHT |
The first call with this Idempotency-Key is still running. |
| 413 | PAYLOAD_TOO_LARGE |
|
| 415 | UNSUPPORTED_MEDIA |
|
| 422 | IDEMPOTENCY_MISMATCH |
The same Idempotency-Key was sent with a different request. |
| 429 | RATE_LIMITED |
Too many calls: wait Retry-After seconds. |
Rate limitsPermalink
Counted with every other call of the organisation, by plan: Pricing. The answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; more on rate limits.