---
title: Endpoints públicos e SDK v1
description: Referência separada de resolução, telemetria, recuperação, detecção e associação.
---

Estas interfaces existentes usam bases diferentes da API administrativa. Use os hosts exatos autorizados da sua instalação. Não envie chaves administrativas. Os hosts e tokens abaixo são fictícios. Leia [o ciclo e os limites](/sdk/contratos-publicos/) e consulte [o OpenAPI público](/contratos-publicos/). Detecção exige opt-in e recuperação tem capacidade transitória; exemplos não criam desafios ou recibos válidos.

## GET /v1/links/{id}

Resolver metadados públicos. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: `https://edge.agilink.invalid/functions/v1/api`.

| Parâmetro | Local | Obrigatório |
| --- | --- | --- |
| `id` | path | sim |
| `appId` | query | sim |

Sem corpo de requisição. Associações também aceitam HEAD com corpo de resposta vazio.

```sh
curl --request GET 'https://edge.agilink.invalid/functions/v1/api/v1/links/go.example.com~-a~-produto?appId=app_loja'
```

Resposta `200`: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

```json
{
  "version": 1,
  "link": {
    "id": "go.example.com~-a~-produto",
    "appId": "app_loja",
    "domain": "go.example.com",
    "prefix": "a",
    "slug": "produto",
    "appPath": "produto/123",
    "title": "Produto",
    "description": null,
    "imageUrl": null,
    "webUrl": "https://shop.example.com/produto/123",
    "webOnly": false,
    "parameters": {
      "sku": "123"
    }
  }
}
```

Erros documentados: `400`, `403`, `404`, `503`. Erros do Worker podem ter corpo vazio. Etapas de recuperação podem responder `200 {"accepted":false}`; ACK HTTP não significa conteúdo exibido. Consulte os schemas e o guia para condições, validade, retry e envelopes.

[Página própria desta operação](/sdk/operacoes/get_v1_links__id_/).

## POST /v1/events

Enviar lote de telemetria client_reported. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: `https://edge.agilink.invalid/functions/v1/api`.

| Campo | Tipo | Obrigatório |
| --- | --- | --- |
| `version` | constante | sim |
| `appId` | string | sim |
| `events` | array | sim |

```json
{
  "version": 1,
  "appId": "app_loja",
  "events": [
    {
      "eventId": "80000000-0000-4000-8000-000000000001",
      "openId": "80000000-0000-4000-8000-000000000002",
      "type": "app_open",
      "linkId": "go.example.com~-a~-produto",
      "occurredAt": "2026-10-19T12:00:00Z",
      "platform": "ios",
      "entryMethod": "https"
    }
  ]
}
```

```sh
curl --request POST 'https://edge.agilink.invalid/functions/v1/api/v1/events' \
  --header 'Content-Type: application/json' \
  --data '{"version":1,"appId":"app_loja","events":[{"eventId":"80000000-0000-4000-8000-000000000001","openId":"80000000-0000-4000-8000-000000000002","type":"app_open","linkId":"go.example.com~-a~-produto","occurredAt":"2026-10-19T12:00:00Z","platform":"ios","entryMethod":"https"}]}'
```

Resposta `200`: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

```json
{
  "version": 1,
  "results": [
    {
      "eventId": "80000000-0000-4000-8000-000000000001",
      "status": "accepted"
    }
  ]
}
```

Erros documentados: `400`, `403`, `413`, `503`. Erros do Worker podem ter corpo vazio. Etapas de recuperação podem responder `200 {"accepted":false}`; ACK HTTP não significa conteúdo exibido. Consulte os schemas e o guia para condições, validade, retry e envelopes.

[Página própria desta operação](/sdk/operacoes/post_v1_events/).

## POST /v1/recovery/preview

Consultar recuperação sem consumir claim. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: `https://edge.agilink.invalid/functions/v1/api`.

| Campo | Tipo | Obrigatório |
| --- | --- | --- |
| `version` | constante | sim |
| `appId` | string | sim |
| `token` | string | sim |

```json
{
  "version": 1,
  "appId": "app_loja",
  "token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
}
```

```sh
curl --request POST 'https://edge.agilink.invalid/functions/v1/api/v1/recovery/preview' \
  --header 'Content-Type: application/json' \
  --data '{"version":1,"appId":"app_loja","token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"}'
```

Resposta `200`: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

```json
{
  "version": 1,
  "appId": "app_loja",
  "linkId": "go.example.com~-a~-produto",
  "context": {
    "publicUri": "https://go.example.com/a/produto"
  },
  "expiresAt": "2026-10-26T12:00:00Z"
}
```

Erros documentados: `400`, `403`, `404`, `409`, `410`, `413`, `429`, `503`. Erros do Worker podem ter corpo vazio. Etapas de recuperação podem responder `200 {"accepted":false}`; ACK HTTP não significa conteúdo exibido. Consulte os schemas e o guia para condições, validade, retry e envelopes.

[Página própria desta operação](/sdk/operacoes/post_v1_recovery_preview/).

## POST /v1/recovery/redeem

Reivindicar recuperação com claim persistido. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: `https://edge.agilink.invalid/functions/v1/api`.

| Campo | Tipo | Obrigatório |
| --- | --- | --- |
| `version` | constante | sim |
| `appId` | string | sim |
| `token` | string | sim |
| `claimId` | string | sim |

```json
{
  "version": 1,
  "appId": "app_loja",
  "token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "claimId": "80000000-0000-4000-8000-000000000002"
}
```

```sh
curl --request POST 'https://edge.agilink.invalid/functions/v1/api/v1/recovery/redeem' \
  --header 'Content-Type: application/json' \
  --data '{"version":1,"appId":"app_loja","token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA","claimId":"80000000-0000-4000-8000-000000000002"}'
```

Resposta `200`: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

```json
{
  "version": 1,
  "appId": "app_loja",
  "linkId": "go.example.com~-a~-produto",
  "context": {
    "publicUri": "https://go.example.com/a/produto"
  },
  "expiresAt": "2026-10-26T12:00:00Z"
}
```

Erros documentados: `400`, `403`, `404`, `409`, `410`, `413`, `429`, `503`. Erros do Worker podem ter corpo vazio. Etapas de recuperação podem responder `200 {"accepted":false}`; ACK HTTP não significa conteúdo exibido. Consulte os schemas e o guia para condições, validade, retry e envelopes.

[Página própria desta operação](/sdk/operacoes/post_v1_recovery_redeem/).

## POST /v1/recovery/stage

Registrar etapa declarada da recuperação. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: `https://edge.agilink.invalid/functions/v1/api`.

| Campo | Tipo | Obrigatório |
| --- | --- | --- |
| `version` | constante | sim |
| `appId` | string | sim |
| `token` | string | sim |
| `eventId` | string | sim |
| `stage` | enum | sim |

```json
{
  "version": 1,
  "appId": "app_loja",
  "token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "eventId": "80000000-0000-4000-8000-000000000001",
  "stage": "copied"
}
```

```sh
curl --request POST 'https://edge.agilink.invalid/functions/v1/api/v1/recovery/stage' \
  --header 'Content-Type: application/json' \
  --data '{"version":1,"appId":"app_loja","token":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA","eventId":"80000000-0000-4000-8000-000000000001","stage":"copied"}'
```

Resposta `200`: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

```json
{
  "accepted": true
}
```

Erros documentados: `400`, `403`, `413`, `503`. Erros do Worker podem ter corpo vazio. Etapas de recuperação podem responder `200 {"accepted":false}`; ACK HTTP não significa conteúdo exibido. Consulte os schemas e o guia para condições, validade, retry e envelopes.

[Página própria desta operação](/sdk/operacoes/post_v1_recovery_stage/).

## POST /_agilink/recovery/detection/challenge

Detecção opcional: challenge. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: `https://go.agilink.invalid`.

| Campo | Tipo | Obrigatório |
| --- | --- | --- |
| `appId` | string | sim |
| `kind` | enum | sim |
| `linkId` | string | não |

```json
{
  "appId": "app_loja",
  "kind": "attempt"
}
```

```sh
curl --request POST 'https://go.agilink.invalid/_agilink/recovery/detection/challenge' \
  --header 'Content-Type: application/json' \
  --data '{"appId":"app_loja","kind":"attempt"}'
```

Resposta `200`: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

```json
{
  "version": 1,
  "nonce": "80000000-0000-4000-8000-000000000002",
  "challenge": "<challenge-assinado>",
  "expiresAt": "2026-10-19T12:02:00Z"
}
```

Erros documentados: `400`, `403`, `404`, `405`, `409`, `410`, `413`, `415`, `429`, `502`, `503`. Erros do Worker podem ter corpo vazio. Etapas de recuperação podem responder `200 {"accepted":false}`; ACK HTTP não significa conteúdo exibido. Consulte os schemas e o guia para condições, validade, retry e envelopes.

[Página própria desta operação](/sdk/operacoes/post__agilink_recovery_detection_challenge/).

## POST /_agilink/recovery/detection/click

Detecção opcional: click. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: `https://go.agilink.invalid`.

| Campo | Tipo | Obrigatório |
| --- | --- | --- |
| `appId` | string | sim |
| `challenge` | string | sim |
| `signals` | DetectionSignals | sim |

```json
{
  "appId": "app_loja",
  "challenge": "<challenge-assinado>",
  "signals": {
    "platform": "ios",
    "family": "iphone",
    "osVersion": "18.0",
    "language": "pt-BR",
    "timezone": "America/Sao_Paulo",
    "screen": {
      "width": 390,
      "height": 844,
      "scale": 3
    }
  }
}
```

```sh
curl --request POST 'https://go.agilink.invalid/_agilink/recovery/detection/click' \
  --header 'Content-Type: application/json' \
  --data '{"appId":"app_loja","challenge":"<challenge-assinado>","signals":{"platform":"ios","family":"iphone","osVersion":"18.0","language":"pt-BR","timezone":"America/Sao_Paulo","screen":{"width":390,"height":844,"scale":3}}}'
```

Resposta `200`: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

```json
{
  "version": 1,
  "mode": "detection",
  "accepted": true,
  "intentReceipt": "<recibo-de-intencao>"
}
```

Erros documentados: `400`, `403`, `404`, `405`, `409`, `410`, `413`, `415`, `429`, `502`, `503`. Erros do Worker podem ter corpo vazio. Etapas de recuperação podem responder `200 {"accepted":false}`; ACK HTTP não significa conteúdo exibido. Consulte os schemas e o guia para condições, validade, retry e envelopes.

[Página própria desta operação](/sdk/operacoes/post__agilink_recovery_detection_click/).

## POST /_agilink/recovery/detection/intent

Detecção opcional: intent. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: `https://go.agilink.invalid`.

| Campo | Tipo | Obrigatório |
| --- | --- | --- |
| `appId` | string | sim |
| `intentReceipt` | string | sim |

```json
{
  "appId": "app_loja",
  "intentReceipt": "<recibo-de-intencao>"
}
```

```sh
curl --request POST 'https://go.agilink.invalid/_agilink/recovery/detection/intent' \
  --header 'Content-Type: application/json' \
  --data '{"appId":"app_loja","intentReceipt":"<recibo-de-intencao>"}'
```

Resposta `200`: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

```json
{
  "version": 1,
  "mode": "detection",
  "accepted": true
}
```

Erros documentados: `400`, `403`, `404`, `405`, `409`, `410`, `413`, `415`, `429`, `502`, `503`. Erros do Worker podem ter corpo vazio. Etapas de recuperação podem responder `200 {"accepted":false}`; ACK HTTP não significa conteúdo exibido. Consulte os schemas e o guia para condições, validade, retry e envelopes.

[Página própria desta operação](/sdk/operacoes/post__agilink_recovery_detection_intent/).

## POST /_agilink/recovery/detection/attempt

Detecção opcional: attempt. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: `https://go.agilink.invalid`.

| Campo | Tipo | Obrigatório |
| --- | --- | --- |
| `appId` | string | sim |
| `challenge` | string | sim |
| `attemptId` | string | sim |
| `signals` | DetectionSignals | sim |

```json
{
  "appId": "app_loja",
  "challenge": "<challenge-assinado>",
  "attemptId": "80000000-0000-4000-8000-000000000002",
  "signals": {
    "platform": "ios",
    "family": "iphone",
    "osVersion": "18.0",
    "language": "pt-BR",
    "timezone": "America/Sao_Paulo",
    "screen": {
      "width": 390,
      "height": 844,
      "scale": 3
    }
  }
}
```

```sh
curl --request POST 'https://go.agilink.invalid/_agilink/recovery/detection/attempt' \
  --header 'Content-Type: application/json' \
  --data '{"appId":"app_loja","challenge":"<challenge-assinado>","attemptId":"80000000-0000-4000-8000-000000000002","signals":{"platform":"ios","family":"iphone","osVersion":"18.0","language":"pt-BR","timezone":"America/Sao_Paulo","screen":{"width":390,"height":844,"scale":3}}}'
```

Resposta `200`: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

```json
{
  "version": 1,
  "mode": "detection",
  "status": "no_match",
  "reason": "no_candidate",
  "policyVersion": "agilink-shadow-v4-context"
}
```

Erros documentados: `400`, `403`, `404`, `405`, `409`, `410`, `413`, `415`, `429`, `502`, `503`. Erros do Worker podem ter corpo vazio. Etapas de recuperação podem responder `200 {"accepted":false}`; ACK HTTP não significa conteúdo exibido. Consulte os schemas e o guia para condições, validade, retry e envelopes.

[Página própria desta operação](/sdk/operacoes/post__agilink_recovery_detection_attempt/).

## POST /_agilink/recovery/detection/claim

Detecção opcional: claim. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: `https://go.agilink.invalid`.

| Campo | Tipo | Obrigatório |
| --- | --- | --- |
| `appId` | string | sim |
| `receipt` | string | sim |
| `confirmed` | boolean | sim |

```json
{
  "appId": "app_loja",
  "receipt": "<recibo-do-candidato>",
  "confirmed": true
}
```

```sh
curl --request POST 'https://go.agilink.invalid/_agilink/recovery/detection/claim' \
  --header 'Content-Type: application/json' \
  --data '{"appId":"app_loja","receipt":"<recibo-do-candidato>","confirmed":true}'
```

Resposta `200`: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

```json
{
  "version": 1,
  "mode": "detection",
  "policyVersion": "agilink-shadow-v4-context",
  "publicUri": "https://go.example.com/a/produto",
  "linkId": "go.example.com~-a~-produto",
  "attemptId": "80000000-0000-4000-8000-000000000002"
}
```

Erros documentados: `400`, `403`, `404`, `405`, `409`, `410`, `413`, `415`, `429`, `502`, `503`. Erros do Worker podem ter corpo vazio. Etapas de recuperação podem responder `200 {"accepted":false}`; ACK HTTP não significa conteúdo exibido. Consulte os schemas e o guia para condições, validade, retry e envelopes.

[Página própria desta operação](/sdk/operacoes/post__agilink_recovery_detection_claim/).

## GET /.well-known/assetlinks.json

Consultar associação Android. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: `https://go.agilink.invalid`.

Sem corpo de requisição. Associações também aceitam HEAD com corpo de resposta vazio.

```sh
curl --request GET 'https://go.agilink.invalid/.well-known/assetlinks.json'
```

Resposta `200`: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

```json
[]
```

Erros documentados: `404`, `405`, `503`. Erros do Worker podem ter corpo vazio. Etapas de recuperação podem responder `200 {"accepted":false}`; ACK HTTP não significa conteúdo exibido. Consulte os schemas e o guia para condições, validade, retry e envelopes.

[Página própria desta operação](/sdk/operacoes/get__well_known_assetlinks_json/).

## GET /.well-known/apple-app-site-association

Consultar associação iOS. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: `https://go.agilink.invalid`.

Sem corpo de requisição. Associações também aceitam HEAD com corpo de resposta vazio.

```sh
curl --request GET 'https://go.agilink.invalid/.well-known/apple-app-site-association'
```

Resposta `200`: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

```json
{
  "applinks": {
    "apps": [],
    "details": []
  }
}
```

Erros documentados: `404`, `405`, `503`. Erros do Worker podem ter corpo vazio. Etapas de recuperação podem responder `200 {"accepted":false}`; ACK HTTP não significa conteúdo exibido. Consulte os schemas e o guia para condições, validade, retry e envelopes.

[Página própria desta operação](/sdk/operacoes/get__well_known_apple_app_site_association/).

## GET /apple-app-site-association

Consultar alias AASA. Contrato público existente, separado de administração. Detecção exige opt-in; não chamar sua rota Edge interna diretamente. Capacidades e validade são revalidadas no servidor.

Base de exemplo: `https://go.agilink.invalid`.

Sem corpo de requisição. Associações também aceitam HEAD com corpo de resposta vazio.

```sh
curl --request GET 'https://go.agilink.invalid/apple-app-site-association'
```

Resposta `200`: Sucesso; exemplos fictícios. ACKs de telemetria devem ser lidos por evento.

```json
{
  "applinks": {
    "apps": [],
    "details": []
  }
}
```

Erros documentados: `404`, `405`, `503`. Erros do Worker podem ter corpo vazio. Etapas de recuperação podem responder `200 {"accepted":false}`; ACK HTTP não significa conteúdo exibido. Consulte os schemas e o guia para condições, validade, retry e envelopes.

[Página própria desta operação](/sdk/operacoes/get_apple_app_site_association/).