---
title: Criar um link
description: Request e response de referência para a criação de um link.
---
:::note[Disponível em homologação]
Endpoint disponível em `https://api.staging.agilink.io/v1`. Os exemplos abaixo são gerados dos mesmos dados validados pelo contrato e usam um host fictício.
:::

Cria um link em aplicativo e domínio autorizados. A credencial precisa de `links:create` e acesso ao aplicativo. A publicação no redirecionador pode continuar pendente após o cadastro.

## Requisição

`POST /v1/links`, com `Authorization: Bearer <sua-chave>`, `Content-Type: application/json` e `Idempotency-Key: 10000000-0000-4000-8000-000000000001`.

```json
{
  "appId": "app_loja",
  "domain": "go.example.com",
  "prefix": "ofertas",
  "slug": "tenis",
  "title": "Tênis da campanha",
  "desktopUrl": "https://shop.example.com/produtos/tenis",
  "appPath": "produtos/tenis"
}
```

`appPath` é relativo, sem barra inicial. Use o caminho que seu aplicativo reconhece. O domínio e o aplicativo deste exemplo são fictícios.

## cURL

```sh
curl --request POST 'https://api.staging.agilink.io/v1/links' \
  --header 'Authorization: Bearer <sua-chave>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 10000000-0000-4000-8000-000000000001' \
  --data '{"appId":"app_loja","domain":"go.example.com","prefix":"ofertas","slug":"tenis","title":"Tênis da campanha","desktopUrl":"https://shop.example.com/produtos/tenis","appPath":"produtos/tenis"}'
```

## Resposta

`201 Created`, com `Location: /v1/links/go.example.com~-ofertas~-tenis` e `ETag: "20000000-0000-4000-8000-000000000001"`.

```json
{
  "data": {
    "id": "go.example.com~-ofertas~-tenis",
    "appId": "app_loja",
    "domain": "go.example.com",
    "prefix": "ofertas",
    "slug": "tenis",
    "url": "https://go.example.com/ofertas/tenis",
    "title": "Tênis da campanha",
    "description": null,
    "imageUrl": null,
    "desktopUrl": "https://shop.example.com/produtos/tenis",
    "appPath": "produtos/tenis",
    "parameters": {},
    "webOnly": false,
    "behavior": "manual",
    "group": "operational",
    "origin": "api",
    "revision": "20000000-0000-4000-8000-000000000001",
    "createdAt": "2026-10-19T20:00:00Z",
    "updatedAt": "2026-10-19T20:00:00Z",
    "publication": {
      "status": "pending",
      "desiredRevision": "20000000-0000-4000-8000-000000000001",
      "confirmedRevision": null,
      "updatedAt": "2026-10-19T20:00:00Z"
    }
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}
```

Consulte o link e sua publicação para acompanhar a revisão. Não confunda `201` com sincronização já confirmada em todos os pontos.

## Erros e repetição

| Status | Quando ocorre | Próxima ação |
| --- | --- | --- |
| 401 | Chave inválida, expirada ou revogada | Verificar credencial |
| 403 | Falta de permissão | Solicitar permissão ao dono |
| 404 | Aplicativo/recurso fora do acesso autorizado | Conferir app e domínio |
| 409 | Slug ocupado, idempotência conflitante ou em andamento | Consultar o resultado; preservar a intenção |
| 422 | Dados de domínio inválidos | Corrigir os campos indicados |
| 429 | Limite excedido | Aguardar `Retry-After` |

Em timeout ou resultado incerto, repita a mesma intenção com a mesma chave de idempotência e o mesmo corpo dentro da janela de 24 horas. Para alterar um link, consulte a revisão e use `If-Match`; uma revisão antiga retorna:

```json
{
  "error": {
    "code": "revision_conflict",
    "message": "O link foi alterado. Consulte a revisão atual.",
    "details": [
      {
        "field": "If-Match",
        "reason": "stale"
      }
    ],
    "requestId": "req_00000000000040008000000000000001",
    "documentationUrl": "https://docs.agilink.io/api/errors/#revision-conflict"
  }
}
```

Veja os [campos do produto](/produto/links/), as [convenções](/api/contratos/) e a [referência completa da prévia](/referencia/).