GET /links
API · v1 · Homologação · Revisado em · Markdown
Listar/buscar por app, domínio, grupo, estado, tags, pasta, campanha e período. Contrato v1 · disponível em produção e homologação · operação getLinks. Guia funcional · Índice · Schemas · Testar em sandbox.
Autenticação e efeito
Seção intitulada “Autenticação e efeito”Permissão: links:read. 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.
Consulta não altera o recurso. Downloads revalidam autorização e têm prazo/estado conforme o guia.
Parâmetros
Seção intitulada “Parâmetros”| Nome | Local | Obrigatório | Tipo e restrições |
|---|---|---|---|
appId |
query | sim | OpaqueId; {“type”:“string”,“maxLength”:500,“minLength”:1,“pattern”:“^[^/\u0000-\u001f\u007f]+$”} |
cursor |
query | não | Cursor; {“type”:“string”,“maxLength”:2048,“pattern”:“^c1\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$”} |
limit |
query | não | integer; {“type”:“integer”,“minimum”:1,“maximum”:100,“default”:50} |
group |
query | não | main / operational; {“enum”:[“main”,“operational”]} |
domain |
query | não | Domain; {“type”:“string”,“maxLength”:253,“pattern”:“^(?:a-z0-9?\.)+a-z0-9?$”} |
q |
query | não | string; {“type”:“string”,“maxLength”:200} |
order |
query | não | createdAt:desc / createdAt:asc; {“type”:“string”,“enum”:[“createdAt:desc”,“createdAt:asc”],“default”:“createdAt:desc”} |
prefix |
query | não | string; {“type”:“string”,“maxLength”:200} |
origin |
query | não | api / dashboard; {“enum”:[“api”,“dashboard”]} |
createdFrom |
query | não | string; {“type”:“string”,“format”:“date-time”} |
createdTo |
query | não | string; {“type”:“string”,“format”:“date-time”} |
folderId |
query | não | string; {“type”:“string”} |
campaignId |
query | não | string; {“type”:“string”} |
tagId |
query | não | string; {“type”:“string”} |
state |
query | não | string; {“type”:“string”} |
archived |
query | não | string; {“type”:“string”} |
Paginação por cursor assinado; preserve credencial, concessão, filtros, ordem e limite. Cursor expira em 15 minutos. A lista mutável não fornece snapshot. Use pagination.nextCursor até hasMore=false.
Corpo e semântica
Seção intitulada “Corpo e semântica”Sem corpo. Envie os parâmetros na URL e os headers indicados.
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.
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 GET 'https://api.staging.agilink.io/v1/links?appId=app_loja' \ --header 'Authorization: Bearer <credencial>'JavaScript / TypeScript
Seção intitulada “JavaScript / TypeScript”// Node.js 22+. Defina AGILINK_API_KEY no ambiente do servidor.const response = await fetch('https://api.staging.agilink.io/v1/links?appId=app_loja', { method: 'GET', headers: { "Authorization": `Bearer ${process.env.AGILINK_API_KEY}`}, 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 3.10+; pip install requestsimport osimport requestsheaders = { "Authorization": "Bearer " + os.environ["AGILINK_API_KEY"]}response = requests.request( 'GET', 'https://api.staging.agilink.io/v1/links?appId=app_loja', headers=headers, 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 200
Seção intitulada “Response 200”Sucesso. 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 |
{ "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" } } ], "pagination": { "nextCursor": null, "hasMore": false }, "meta": { "requestId": "req_00000000000040008000000000000001" }}| Campo | Tipo | Obrigatório | Significado e limites |
|---|---|---|---|
data |
array | sim | Resultado tipado da operação. Até 100 itens |
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. |
pagination |
Pagination | sim | Continuação da lista; não é snapshot. |
pagination.nextCursor |
Cursor ou null | sim | Cursor assinado; conserve filtros, credencial e limite. |
pagination.hasMore |
boolean | sim | Indica se há continuação. |
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
Seção intitulada “Falhas, revisão e repetição”Respeite Retry-After quando existir. Leituras podem ser repetidas após falhas transitórias. 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. |
| 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
Seção intitulada “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
Seção intitulada “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 429
Seção intitulada “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
Seção intitulada “Schema completo e próximos passos”Schema de request
{ "description": "Sem corpo"}Schema de response
{ "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "items": { "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" ] }, "maxItems": 100 }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "type": "object", "additionalProperties": false, "properties": { "requestId": { "$ref": "#/components/schemas/RequestId" } }, "required": [ "requestId" ] } }, "required": [ "data", "pagination", "meta" ]}Convenções e limites · Erros · Receitas completas · Guia funcional.