POST /links/{linkId}/duplicate

API · v1 · Produção · Revisado em 2026-10-20 · Markdown

Criar novo link a partir de configuração existente. Contrato v1 · disponível em produção e homologação · operação duplicateLinksLinkId. Guia funcional · Índice · Schemas · Testar em sandbox.

Autenticação e efeito

Permissão: links:create. Sessão humana ou chave de servidor limitada ao proprietário e aos aplicativos autorizados. OAuth/MCP ainda não estão disponíveis. Uma chave de exemplo deve incluir somente esta permissão e as leituras necessárias ao seu fluxo, restrita a app_loja; emita-a na área autenticada de desenvolvedores.

Disponível em produção e homologação; sujeito às capacidades do app e à configuração do provedor. OAuth só será aceito após B1b. Campos desconhecidos rejeitados. Consulte os ADRs para regras semânticas além do JSON Schema.

O efeito é autenticado, auditado e pode gerar publicação eventual e eventos do recurso. Links/domínios/templates podem precisar de propagação antes de aparecerem publicamente. Não muda identidade de link implicitamente. Dependências e capabilities podem bloquear a ação. O status confirma a persistência descrita, sem prometer propagação global imediata.

Parâmetros

Nome	Local	Obrigatório	Tipo e restrições
`linkId`	path	sim	LinkId; {“type”:“string”,“maxLength”:500,“pattern”:“^[a-z0-9.-]+~~-(?:(?!~~-)[A-Za-z0-9._-])*-(?:(?!~~-)[A-Za-z0-9._~~-])+$”}
`Idempotency-Key`	header	sim	UUID v4 por intenção. Recibo por 24h. Mudança de payload/precondição retorna 409. Segredo de chave não é reexibido. IdempotencyKey; {“type”:“string”,“maxLength”:36,“pattern”:“^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$”}

Corpo e semântica

Content-Type: application/json. Campos desconhecidos são rejeitados no envelope.

Campo	Tipo	Obrigatório	Significado e limites
`slug`	string	sim	Segmento final da identidade. Até 200 caracteres; Formato validado pelo schema
`prefix`	string	não	Prefixo de caminho, sem barras. Até 200 caracteres; Formato validado pelo schema
`domain`	Domain	não	Hostname, sem protocolo ou caminho.
`title`	string ou null	não	Título público.

Omitir campos opcionais usa o default documentado ou preserva o valor em PATCH. null só é aceito nos campos cujo schema permite null, com efeito de limpar/desvincular indicado no guia. Arrays enviados substituem a coleção quando o endpoint define atualização completa; não implicam merge. Identificadores/owner/app de um recurso existente não são transferidos por PATCH. Herança de templates/UTMs segue o guia, sem alterar links anteriores por cópia automática.

Request mínimo

{
  "slug": "tenis-copia"
}

Request completo de referência

{
  "slug": "tenis-copia"
}

cURL

AGILINK_API_KEY deve ficar no servidor. Os placeholders abaixo são fictícios. Preserve Idempotency-Key e payload ao repetir uma intenção após timeout.

curl --request POST 'https://api.staging.agilink.io/v1/links/go.example.com~-ofertas~-tenis/duplicate' \
  --header 'Authorization: Bearer <credencial>' \
  --header 'Idempotency-Key: 10000000-0000-4000-8000-000000000001' \
  --header 'Content-Type: application/json' \
  --data '{"slug":"tenis-copia"}'

JavaScript / TypeScript

// Node.js 22+. Defina AGILINK_API_KEY no ambiente do servidor.
const response = await fetch('https://api.staging.agilink.io/v1/links/go.example.com~-ofertas~-tenis/duplicate', {
  method: 'POST',
  headers: {
  "Authorization": `Bearer ${process.env.AGILINK_API_KEY}`,
  "Idempotency-Key": "10000000-0000-4000-8000-000000000001",
  "Content-Type": "application/json"
},
  body: JSON.stringify({
  "slug": "tenis-copia"
}),
  redirect: 'error', signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error('HTTP '+response.status+' requestId='+response.headers.get('X-Request-Id'));
const result = await response.json();
console.log(result);

Python

# Python 3.10+; pip install requests
import os
import requests
headers = {
  "Authorization": "Bearer " + os.environ["AGILINK_API_KEY"],
  "Idempotency-Key": "10000000-0000-4000-8000-000000000001"
}
response = requests.request(
    'POST', 'https://api.staging.agilink.io/v1/links/go.example.com~-ofertas~-tenis/duplicate',
    headers=headers, json={"slug":"tenis-copia"},
    timeout=30, allow_redirects=False)
if not 200 <= response.status_code < 300:
    raise RuntimeError(f'HTTP {response.status_code}; requestId={response.headers.get("X-Request-Id")}')
result = response.json()
print(result)

Response 201

Criado. Exemplo fictício.

Header	Significado	Exemplo
`X-Request-Id`	Identificador gerado pelo servidor, inclusive para falhas e replays.	conforme resposta
`Cache-Control`	Respostas administrativas não podem ser armazenadas.	no-store, no-transform
`ETag`	Revisão forte, a enviar em If-Match na alteração.	“20000000-0000-4000-8000-000000000001”
`Location`	Endereço relativo do recurso criado.	/v1/links/{linkId}/duplicate/30000000-0000-4000-8000-000000000001

{
  "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"
  }
}

Campo	Tipo	Obrigatório	Significado e limites
`data`	object	sim	Resultado tipado da operação.
`data.id`	LinkId	sim	Identificador estável do recurso.
`data.appId`	string	sim	Aplicativo proprietário; precisa estar autorizado. Até 500 caracteres; Formato validado pelo schema
`data.domain`	Domain	sim	Hostname, sem protocolo ou caminho.
`data.prefix`	string	sim	Prefixo de caminho, sem barras. Até 200 caracteres; Formato validado pelo schema
`data.slug`	string	sim	Segmento final da identidade. Até 200 caracteres; Formato validado pelo schema
`data.url`	string	sim	Endereço do recurso; não acrescente credenciais. Até 4096 caracteres; uri; Formato validado pelo schema
`data.folderId`	string ou null	não	Valor tipado; formato e restrições completos no schema abaixo.
`data.campaignId`	string ou null	não	Valor tipado; formato e restrições completos no schema abaixo.
`data.lifecycle`	LinkLifecycle	não	Valor tipado; formato e restrições completos no schema abaixo.
`data.lifecycle.archived`	boolean	sim	Valor tipado; formato e restrições completos no schema abaixo.
`data.lifecycle.paused`	boolean	sim	Valor tipado; formato e restrições completos no schema abaixo.
`data.lifecycle.startsAt`	AnalyticsInstant ou null	sim	Valor tipado; formato e restrições completos no schema abaixo.
`data.lifecycle.expiresAt`	AnalyticsInstant ou null	sim	Fim de validade; não amplia concessões.
`data.lifecycle.fallbackUrl`	string ou null	sim	Valor tipado; formato e restrições completos no schema abaixo.
`data.utm`	UtmParameters	não	Valor tipado; formato e restrições completos no schema abaixo.
`data.utm.utm_source`	string	não	Valor tipado; formato e restrições completos no schema abaixo. Até 200 caracteres; Formato validado pelo schema
`data.utm.utm_medium`	string	não	Valor tipado; formato e restrições completos no schema abaixo. Até 200 caracteres; Formato validado pelo schema
`data.utm.utm_campaign`	string	não	Valor tipado; formato e restrições completos no schema abaixo. Até 200 caracteres; Formato validado pelo schema
`data.utm.utm_term`	string	não	Valor tipado; formato e restrições completos no schema abaixo. Até 200 caracteres; Formato validado pelo schema
`data.utm.utm_content`	string	não	Valor tipado; formato e restrições completos no schema abaixo. Até 200 caracteres; Formato validado pelo schema
`data.title`	string ou null	sim	Título público.
`data.description`	string ou null	não	Texto de apresentação.
`data.imageUrl`	string ou null	não	Valor tipado; formato e restrições completos no schema abaixo.
`data.desktopUrl`	string ou null	sim	Valor tipado; formato e restrições completos no schema abaixo.
`data.playStoreUrl`	string ou null	não	Valor tipado; formato e restrições completos no schema abaixo.
`data.appStoreUrl`	string ou null	não	Valor tipado; formato e restrições completos no schema abaixo.
`data.appPath`	string ou null	não	Valor tipado; formato e restrições completos no schema abaixo.
`data.parameters`	Parameters	não	Parâmetros tipados do link; limites UTF-8 também se aplicam.
`data.webOnly`	boolean	não	Direcionamento web; exige destino web válido.
`data.behavior`	manual / automatic / intelligent	não	Valor tipado; formato e restrições completos no schema abaixo.
`data.group`	main / operational	sim	Grupo main/operational; diferente de pasta/campanha.
`data.templateData`	object	não	Valor tipado; formato e restrições completos no schema abaixo.
`data.templateSelection`	object	não	Herança, oficial ou versão customizada publicada.
`data.templateSelection.android`	object ou object ou object	não	Valor tipado; formato e restrições completos no schema abaixo.
`data.templateSelection.android.mode`	objeto	sim	Valor tipado; formato e restrições completos no schema abaixo.
`data.templateSelection.android.mode`	objeto	sim	Valor tipado; formato e restrições completos no schema abaixo.
`data.templateSelection.android.mode`	objeto	sim	Valor tipado; formato e restrições completos no schema abaixo.
`data.templateSelection.android.templateId`	string	sim	Valor tipado; formato e restrições completos no schema abaixo. uuid
`data.templateSelection.android.version`	integer	sim	Valor tipado; formato e restrições completos no schema abaixo. Mínimo 1
`data.templateSelection.ios`	object ou object ou object	não	Valor tipado; formato e restrições completos no schema abaixo.
`data.templateSelection.ios.mode`	objeto	sim	Valor tipado; formato e restrições completos no schema abaixo.
`data.templateSelection.ios.mode`	objeto	sim	Valor tipado; formato e restrições completos no schema abaixo.
`data.templateSelection.ios.mode`	objeto	sim	Valor tipado; formato e restrições completos no schema abaixo.
`data.templateSelection.ios.templateId`	string	sim	Valor tipado; formato e restrições completos no schema abaixo. uuid
`data.templateSelection.ios.version`	integer	sim	Valor tipado; formato e restrições completos no schema abaixo. Mínimo 1
`data.templateSelection.recovery`	object ou object ou object	não	Valor tipado; formato e restrições completos no schema abaixo.
`data.templateSelection.recovery.mode`	objeto	sim	Valor tipado; formato e restrições completos no schema abaixo.
`data.templateSelection.recovery.mode`	objeto	sim	Valor tipado; formato e restrições completos no schema abaixo.
`data.templateSelection.recovery.mode`	objeto	sim	Valor tipado; formato e restrições completos no schema abaixo.
`data.templateSelection.recovery.templateId`	string	sim	Valor tipado; formato e restrições completos no schema abaixo. uuid
`data.templateSelection.recovery.version`	integer	sim	Valor tipado; formato e restrições completos no schema abaixo. Mínimo 1
`data.origin`	dashboard / api	sim	Origem de criação, preservada.
`data.revision`	string	sim	Revisão forte para If-Match; muda ao editar. uuid
`data.createdAt`	string	sim	Instante de criação com fuso. date-time
`data.updatedAt`	string	sim	Instante da última alteração. date-time
`data.publication`	object	sim	Confirmação eventual da projeção pública.
`data.publication.status`	pending / synced / failed	sim	Estado atual; consulte as transições no guia do recurso.
`data.publication.desiredRevision`	string	sim	Valor tipado; formato e restrições completos no schema abaixo. uuid
`data.publication.confirmedRevision`	string ou null	sim	Valor tipado; formato e restrições completos no schema abaixo.
`data.publication.updatedAt`	string	sim	Instante da última alteração. date-time
`data.tagIds`	array	não	Valor tipado; formato e restrições completos no schema abaixo. Até 20 itens
`data.state`	active / paused / scheduled / expired	não	Estado atual do recurso.
`meta`	object	sim	Correlação e informações da resposta.
`meta.requestId`	RequestId	sim	Identificador de correlação gerado pelo servidor.

Falhas, revisão e repetição

Idempotency-Key UUID v4 é obrigatório, por intenção e credencial, por 24 horas. Em resultado incerto, repita exatamente o mesmo método, URL, corpo, revisão e chave. Alterar a intenção exige nova chave. Segredos de emissão não são reexibidos. Esta operação não exige If-Match. Não faça retry automático ilimitado.

Status	Significado
400	Cabeçalho, query, cursor ou JSON inválido.
401	Credencial inválida, expirada ou revogada.
403	Operação sem permissão ou capacidade desabilitada.
404	Recurso inexistente ou fora dos aplicativos autorizados.
409	Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.
413	Corpo excede o limite.
415	Content-Type incompatível.
422	JSON bem formado com dados de domínio inválidos.
429	Quota excedida. Respeitar Retry-After.
500	Falha interna. Use requestId para diagnóstico.
503	Dependência indisponível; resultado da mutação pode ser incerto.

Exemplo 401

{
  "error": {
    "code": "unauthenticated",
    "message": "Credencial inválida, expirada ou revogada.",
    "requestId": "req_00000000000040008000000000000001",
    "documentationUrl": "https://docs.agilink.io/api/errors/#unauthenticated"
  }
}

Exemplo 403

{
  "error": {
    "code": "insufficient_permission",
    "message": "Operação sem permissão ou capacidade desabilitada.",
    "requestId": "req_00000000000040008000000000000001",
    "documentationUrl": "https://docs.agilink.io/api/errors/#insufficient-permission"
  }
}

Exemplo 409

{
  "error": {
    "code": "idempotency_conflict",
    "message": "Conflito de identidade/idempotência; operação em andamento ou segredo já exibido.",
    "requestId": "req_00000000000040008000000000000001",
    "documentationUrl": "https://docs.agilink.io/api/errors/#idempotency-conflict"
  }
}

Exemplo 429

{
  "error": {
    "code": "rate_limited",
    "message": "Quota excedida. Respeitar Retry-After.",
    "requestId": "req_00000000000040008000000000000001",
    "documentationUrl": "https://docs.agilink.io/api/errors/#rate-limited"
  }
}

Schema completo e próximos passos

Schema de request

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "slug": {
      "type": "string",
      "maxLength": 200,
      "pattern": "^(?!.*~-)(?!\\.{1,2}$)[A-Za-z0-9._~-]*$",
      "minLength": 1
    },
    "prefix": {
      "type": "string",
      "maxLength": 200,
      "pattern": "^(?!.*~-)(?!\\.{1,2}$)[A-Za-z0-9._~-]*$"
    },
    "domain": {
      "$ref": "#/components/schemas/Domain"
    },
    "title": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 1000,
          "pattern": "^[^\\u0000-\\u001f\\u007f]*$"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "slug"
  ]
}

Schema de response

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "data": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": {
          "$ref": "#/components/schemas/LinkId"
        },
        "appId": {
          "type": "string",
          "maxLength": 500,
          "minLength": 1,
          "pattern": "^[^/\\u0000-\\u001f\\u007f]+$"
        },
        "domain": {
          "$ref": "#/components/schemas/Domain"
        },
        "prefix": {
          "type": "string",
          "maxLength": 200,
          "pattern": "^(?!.*~-)(?!\\.{1,2}$)[A-Za-z0-9._~-]*$"
        },
        "slug": {
          "type": "string",
          "maxLength": 200,
          "pattern": "^(?!.*~-)(?!\\.{1,2}$)[A-Za-z0-9._~-]*$",
          "minLength": 1
        },
        "url": {
          "type": "string",
          "maxLength": 4096,
          "format": "uri",
          "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)"
        },
        "folderId": {
          "anyOf": [
            {
              "type": "string",
              "format": "uuid"
            },
            {
              "type": "null"
            }
          ]
        },
        "campaignId": {
          "anyOf": [
            {
              "type": "string",
              "format": "uuid"
            },
            {
              "type": "null"
            }
          ]
        },
        "lifecycle": {
          "$ref": "#/components/schemas/LinkLifecycle"
        },
        "utm": {
          "$ref": "#/components/schemas/UtmParameters"
        },
        "title": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 1000,
              "pattern": "^[^\\u0000-\\u001f\\u007f]*$"
            },
            {
              "type": "null"
            }
          ]
        },
        "description": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 4000,
              "pattern": "^[^\\u0000-\\u001f\\u007f]*$"
            },
            {
              "type": "null"
            }
          ]
        },
        "imageUrl": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 4096,
              "format": "uri",
              "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)"
            },
            {
              "type": "null"
            }
          ]
        },
        "desktopUrl": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 4096,
              "format": "uri",
              "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)"
            },
            {
              "type": "null"
            }
          ]
        },
        "playStoreUrl": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 4096,
              "format": "uri",
              "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)"
            },
            {
              "type": "null"
            }
          ]
        },
        "appStoreUrl": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 4096,
              "format": "uri",
              "pattern": "^https://[^/@?#\\s]+(?:[/?#]|$)"
            },
            {
              "type": "null"
            }
          ]
        },
        "appPath": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 2048,
              "minLength": 1,
              "pattern": "^(?!/)(?!.*[?#\\\\])(?!.*(?:^|/)\\.{1,2}(?:/|$))[^/]+(?:/[^/]+)*$"
            },
            {
              "type": "null"
            }
          ]
        },
        "parameters": {
          "$ref": "#/components/schemas/Parameters"
        },
        "webOnly": {
          "type": "boolean"
        },
        "behavior": {
          "enum": [
            "manual",
            "automatic",
            "intelligent"
          ]
        },
        "group": {
          "enum": [
            "main",
            "operational"
          ]
        },
        "templateData": {
          "type": "object",
          "additionalProperties": {
            "type": [
              "string",
              "number",
              "boolean"
            ]
          }
        },
        "templateSelection": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "android": {
              "oneOf": [
                {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "mode": {
                      "const": "inherit"
                    }
                  },
                  "required": [
                    "mode"
                  ]
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "mode": {
                      "const": "official"
                    }
                  },
                  "required": [
                    "mode"
                  ]
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "mode": {
                      "const": "custom"
                    },
                    "templateId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "version": {
                      "type": "integer",
                      "minimum": 1
                    }
                  },
                  "required": [
                    "mode",
                    "templateId",
                    "version"
                  ]
                }
              ]
            },
            "ios": {
              "oneOf": [
                {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "mode": {
                      "const": "inherit"
                    }
                  },
                  "required": [
                    "mode"
                  ]
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "mode": {
                      "const": "official"
                    }
                  },
                  "required": [
                    "mode"
                  ]
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "mode": {
                      "const": "custom"
                    },
                    "templateId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "version": {
                      "type": "integer",
                      "minimum": 1
                    }
                  },
                  "required": [
                    "mode",
                    "templateId",
                    "version"
                  ]
                }
              ]
            },
            "recovery": {
              "oneOf": [
                {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "mode": {
                      "const": "inherit"
                    }
                  },
                  "required": [
                    "mode"
                  ]
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "mode": {
                      "const": "official"
                    }
                  },
                  "required": [
                    "mode"
                  ]
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "properties": {
                    "mode": {
                      "const": "custom"
                    },
                    "templateId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "version": {
                      "type": "integer",
                      "minimum": 1
                    }
                  },
                  "required": [
                    "mode",
                    "templateId",
                    "version"
                  ]
                }
              ]
            }
          },
          "required": []
        },
        "origin": {
          "enum": [
            "dashboard",
            "api"
          ]
        },
        "revision": {
          "type": "string",
          "format": "uuid"
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time"
        },
        "publication": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "status": {
              "enum": [
                "pending",
                "synced",
                "failed"
              ]
            },
            "desiredRevision": {
              "type": "string",
              "format": "uuid"
            },
            "confirmedRevision": {
              "anyOf": [
                {
                  "type": "string",
                  "format": "uuid"
                },
                {
                  "type": "null"
                }
              ]
            },
            "updatedAt": {
              "type": "string",
              "format": "date-time"
            }
          },
          "required": [
            "status",
            "desiredRevision",
            "confirmedRevision",
            "updatedAt"
          ]
        },
        "tagIds": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "maxItems": 20,
          "uniqueItems": true
        },
        "state": {
          "enum": [
            "active",
            "paused",
            "scheduled",
            "expired"
          ]
        }
      },
      "required": [
        "id",
        "appId",
        "domain",
        "prefix",
        "slug",
        "url",
        "title",
        "desktopUrl",
        "group",
        "origin",
        "revision",
        "createdAt",
        "updatedAt",
        "publication"
      ]
    },
    "meta": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "requestId": {
          "$ref": "#/components/schemas/RequestId"
        }
      },
      "required": [
        "requestId"
      ]
    }
  },
  "required": [
    "data",
    "meta"
  ]
}

Convenções e limites · Erros · Receitas completas · Guia funcional.