Endpoints de aplicativos, links e ativos

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

Estas 25 operações estão em homologação em https://api.staging.agilink.io/v1. Exemplos usam recursos fictícios. A referência interativa contém os schemas completos de cada campo, inclusive objetos internos. Leia também o guia da integração e a migração de tokens.

Todas as requisições usam Authorization: Bearer <credencial>. Sessão humana e chave limitada são indicadas por operação. OAuth depende da Tarefa 2. Mutações exigem Idempotency-Key UUID v4; revisões, quando exigidas, usam If-Match: "<revision>". Nunca envie credenciais em query strings.

GET /links

Listar/buscar por app, domínio, grupo, estado, tags, pasta, campanha e período.

Permissão: links:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`appId`	query	sim	OpaqueId
`cursor`	query	não	Cursor
`limit`	query	não	integer
`group`	query	não	—
`domain`	query	não	Domain
`q`	query	não	string
`order`	query	não	string
`prefix`	query	não	string
`origin`	query	não	—
`createdFrom`	query	não	string
`createdTo`	query	não	string
`folderId`	query	não	string
`campaignId`	query	não	string
`tagId`	query	não	string
`state`	query	não	string
`archived`	query	não	string

Sem corpo de requisição.

Resposta: 200. Sucesso. Exemplo fictício.

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

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

POST /links

Criar link web/deep link com idempotência.

Permissão: links:create. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`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.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição
`appId`	string	sim	Máximo 500 caracteres
`domain`	Domain	sim	Consulte o schema para restrições e campos internos
`prefix`	string	não	Máximo 200 caracteres
`slug`	string	sim	Máximo 200 caracteres
`folderId`	string / null	não	Consulte o schema para restrições e campos internos
`campaignId`	string / null	não	Consulte o schema para restrições e campos internos
`lifecycle`	LinkLifecycle	não	Consulte o schema para restrições e campos internos
`utm`	UtmParameters	não	Consulte o schema para restrições e campos internos
`title`	string / null	não	Consulte o schema para restrições e campos internos
`description`	string / null	não	Consulte o schema para restrições e campos internos
`imageUrl`	string / null	não	Consulte o schema para restrições e campos internos
`desktopUrl`	string / null	não	Consulte o schema para restrições e campos internos
`playStoreUrl`	string / null	não	Consulte o schema para restrições e campos internos
`appStoreUrl`	string / null	não	Consulte o schema para restrições e campos internos
`appPath`	string / null	não	Consulte o schema para restrições e campos internos
`parameters`	Parameters	não	Consulte o schema para restrições e campos internos
`webOnly`	boolean	não	Consulte o schema para restrições e campos internos
`behavior`	—	não	Valores: manual, automatic, intelligent
`group`	—	não	Valores: main, operational
`templateData`	object	não	Consulte o schema para restrições e campos internos
`templateSelection`	object	não	Consulte o schema para restrições e campos internos

{
  "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. Criado. Exemplo fictício.

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

Erros previstos: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503. Veja códigos e repetição.

GET /links/{linkId}

Consultar contrato administrativo e revisão.

Permissão: links:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`linkId`	path	sim	LinkId

Sem corpo de requisição.

Resposta: 200. Sucesso. Exemplo fictício.

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

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

PATCH /links/{linkId}

Atualizar campos mutáveis com revisão.

Permissão: links:update. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`linkId`	path	sim	LinkId
`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.
`If-Match`	header	sim	ETag forte obtido em consulta. Ausência 428; revisão antiga 412.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição
`folderId`	string / null	não	Consulte o schema para restrições e campos internos
`campaignId`	string / null	não	Consulte o schema para restrições e campos internos
`lifecycle`	LinkLifecycle	não	Consulte o schema para restrições e campos internos
`utm`	UtmParameters	não	Consulte o schema para restrições e campos internos
`title`	string / null	não	Consulte o schema para restrições e campos internos
`description`	string / null	não	Consulte o schema para restrições e campos internos
`imageUrl`	string / null	não	Consulte o schema para restrições e campos internos
`desktopUrl`	string / null	não	Consulte o schema para restrições e campos internos
`playStoreUrl`	string / null	não	Consulte o schema para restrições e campos internos
`appStoreUrl`	string / null	não	Consulte o schema para restrições e campos internos
`appPath`	string / null	não	Consulte o schema para restrições e campos internos
`parameters`	Parameters	não	Consulte o schema para restrições e campos internos
`webOnly`	boolean	não	Consulte o schema para restrições e campos internos
`behavior`	—	não	Valores: manual, automatic, intelligent
`group`	—	não	Valores: main, operational
`templateData`	object	não	Consulte o schema para restrições e campos internos
`templateSelection`	object	não	Consulte o schema para restrições e campos internos

{
  "title": "Tênis em promoção"
}

Resposta: 200. Sucesso. Exemplo fictício.

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

Erros previstos: 400, 401, 403, 404, 409, 412, 413, 415, 422, 428, 429, 500, 503. Veja códigos e repetição.

DELETE /links/{linkId}

Exclusão autorizada com revisão e dependências.

Permissão: links:delete. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`linkId`	path	sim	LinkId
`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.
`If-Match`	header	sim	ETag forte obtido em consulta. Ausência 428; revisão antiga 412.

Sem corpo de requisição.

Resposta: 204. Removido. Corpo vazio; publicação da remoção acompanha outbox.

Sem corpo de resposta.

Erros previstos: 400, 401, 403, 404, 409, 412, 413, 422, 428, 429, 500, 503. Veja códigos e repetição.

GET /apps

Apps visíveis à credencial, com paginação.

Permissão: apps:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`limit`	query	não	integer
`cursor`	query	não	Cursor
`q`	query	não	string

Sem corpo de requisição.

Resposta: 200. Sucesso. Exemplo fictício.

{
  "data": [
    {
      "id": "app_loja",
      "name": "Loja",
      "defaultDomain": "go.example.com",
      "desktopUrl": "https://shop.example.com/",
      "playStoreUrl": null,
      "appStoreUrl": null,
      "scheme": "loja",
      "androidPackage": "com.example.loja",
      "iosBundleId": "com.example.loja",
      "revision": "20000000-0000-4000-8000-000000000001",
      "createdAt": "2026-10-19T20:00:00Z",
      "updatedAt": "2026-10-19T20:00:00Z"
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

POST /apps

Criar aplicativo com configurações iniciais.

Permissão: apps:create. Credencial: sessão humana.

Parâmetro	Local	Obrigatório	Significado
`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.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição
`name`	string	sim	Máximo 100 caracteres
`defaultDomain`	Domain / null	não	Consulte o schema para restrições e campos internos
`desktopUrl`	string / null	não	Consulte o schema para restrições e campos internos
`playStoreUrl`	string / null	não	Consulte o schema para restrições e campos internos
`appStoreUrl`	string / null	não	Consulte o schema para restrições e campos internos
`scheme`	string / null	não	Consulte o schema para restrições e campos internos
`androidPackage`	string / null	não	Consulte o schema para restrições e campos internos
`iosBundleId`	string / null	não	Consulte o schema para restrições e campos internos

{
  "name": "Loja",
  "desktopUrl": "https://shop.example.com/",
  "scheme": "loja",
  "androidPackage": "com.example.loja",
  "iosBundleId": "com.example.loja"
}

Resposta: 201. Criado. Exemplo fictício.

{
  "data": {
    "id": "app_loja",
    "name": "Loja",
    "defaultDomain": "go.example.com",
    "desktopUrl": "https://shop.example.com/",
    "playStoreUrl": null,
    "appStoreUrl": null,
    "scheme": "loja",
    "androidPackage": "com.example.loja",
    "iosBundleId": "com.example.loja",
    "revision": "20000000-0000-4000-8000-000000000001",
    "createdAt": "2026-10-19T20:00:00Z",
    "updatedAt": "2026-10-19T20:00:00Z"
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503. Veja códigos e repetição.

GET /apps/{appId}

Consultar cadastro e configuração.

Permissão: apps:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`appId`	path	sim	OpaqueId

Sem corpo de requisição.

Resposta: 200. Sucesso. Exemplo fictício.

{
  "data": {
    "id": "app_loja",
    "name": "Loja",
    "defaultDomain": "go.example.com",
    "desktopUrl": "https://shop.example.com/",
    "playStoreUrl": null,
    "appStoreUrl": null,
    "scheme": "loja",
    "androidPackage": "com.example.loja",
    "iosBundleId": "com.example.loja",
    "revision": "20000000-0000-4000-8000-000000000001",
    "createdAt": "2026-10-19T20:00:00Z",
    "updatedAt": "2026-10-19T20:00:00Z"
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

PATCH /apps/{appId}

Atualizar nome, destinos e campos permitidos.

Permissão: apps:update. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`appId`	path	sim	OpaqueId
`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.
`If-Match`	header	sim	ETag forte obtido em consulta. Ausência 428; revisão antiga 412.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição
`name`	string	não	Máximo 100 caracteres
`defaultDomain`	Domain / null	não	Consulte o schema para restrições e campos internos
`desktopUrl`	string / null	não	Consulte o schema para restrições e campos internos
`playStoreUrl`	string / null	não	Consulte o schema para restrições e campos internos
`appStoreUrl`	string / null	não	Consulte o schema para restrições e campos internos
`scheme`	string / null	não	Consulte o schema para restrições e campos internos
`androidPackage`	string / null	não	Consulte o schema para restrições e campos internos
`iosBundleId`	string / null	não	Consulte o schema para restrições e campos internos

{
  "name": "Loja nova"
}

Resposta: 200. Sucesso. Exemplo fictício.

{
  "data": {
    "id": "app_loja",
    "name": "Loja",
    "defaultDomain": "go.example.com",
    "desktopUrl": "https://shop.example.com/",
    "playStoreUrl": null,
    "appStoreUrl": null,
    "scheme": "loja",
    "androidPackage": "com.example.loja",
    "iosBundleId": "com.example.loja",
    "revision": "20000000-0000-4000-8000-000000000001",
    "createdAt": "2026-10-19T20:00:00Z",
    "updatedAt": "2026-10-19T20:00:00Z"
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 409, 412, 413, 415, 422, 428, 429, 500, 503. Veja códigos e repetição.

DELETE /apps/{appId}

Excluir respeitando links, domínios, templates e histórico.

Permissão: apps:delete. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`appId`	path	sim	OpaqueId
`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.
`If-Match`	header	sim	ETag forte obtido em consulta. Ausência 428; revisão antiga 412.

Sem corpo de requisição.

Resposta: 204. Aplicativo sem dependências excluído; tokens legados revogados. Corpo vazio.

Sem corpo de resposta.

Erros previstos: 400, 401, 403, 404, 409, 412, 413, 422, 428, 429, 500, 503. Veja códigos e repetição.

GET /apps/{appId}/defaults

Padrões de domínio, destinos e apresentação.

Permissão: apps:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`appId`	path	sim	OpaqueId

Sem corpo de requisição.

Resposta: 200. Sucesso. Exemplo fictício.

{
  "data": {
    "appId": "app_loja",
    "domain": "go.example.com",
    "desktopUrl": "https://shop.example.com/",
    "playStoreUrl": null,
    "appStoreUrl": null,
    "revision": "20000000-0000-4000-8000-000000000001"
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

PUT /apps/{appId}/defaults

Padrões de domínio, destinos e apresentação.

Permissão: apps:update. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`appId`	path	sim	OpaqueId
`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.
`If-Match`	header	sim	ETag forte obtido em consulta. Ausência 428; revisão antiga 412.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição
`domain`	Domain / null	sim	Consulte o schema para restrições e campos internos
`desktopUrl`	string / null	sim	Consulte o schema para restrições e campos internos
`playStoreUrl`	string / null	sim	Consulte o schema para restrições e campos internos
`appStoreUrl`	string / null	sim	Consulte o schema para restrições e campos internos

{
  "domain": "go.example.com",
  "desktopUrl": "https://shop.example.com/",
  "playStoreUrl": null,
  "appStoreUrl": null
}

Resposta: 200. Sucesso. Exemplo fictício.

{
  "data": {
    "appId": "app_loja",
    "domain": "go.example.com",
    "desktopUrl": "https://shop.example.com/",
    "playStoreUrl": null,
    "appStoreUrl": null,
    "revision": "20000000-0000-4000-8000-000000000001"
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 409, 412, 413, 415, 422, 428, 429, 500, 503. Veja códigos e repetição.

GET /apps/{appId}/logo

Consultar, associar e remover logo via ativo autorizado.

Permissão: apps:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`appId`	path	sim	OpaqueId

Sem corpo de requisição.

Resposta: 200. Sucesso. Exemplo fictício.

{
  "data": {
    "appId": "app_loja",
    "asset": {
      "id": "50000000-0000-4000-8000-000000000001",
      "appId": "app_loja",
      "url": "https://images.staging.agilink.io/40000000-0000-4000-8000-000000000001/app_loja/50000000-0000-4000-8000-000000000001.png",
      "state": "active",
      "revision": "20000000-0000-4000-8000-000000000001",
      "contentType": "image/png",
      "byteSize": 68,
      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "createdAt": "2026-10-19T20:00:00Z",
      "updatedAt": "2026-10-19T20:00:00Z"
    },
    "revision": "20000000-0000-4000-8000-000000000001"
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

PUT /apps/{appId}/logo

Consultar, associar e remover logo via ativo autorizado.

Permissão: apps:update. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`appId`	path	sim	OpaqueId
`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.
`If-Match`	header	sim	ETag forte obtido em consulta. Ausência 428; revisão antiga 412.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição
`assetId`	string	sim	uuid

{
  "assetId": "50000000-0000-4000-8000-000000000001"
}

Resposta: 200. Sucesso. Exemplo fictício.

{
  "data": {
    "appId": "app_loja",
    "asset": {
      "id": "50000000-0000-4000-8000-000000000001",
      "appId": "app_loja",
      "url": "https://images.staging.agilink.io/40000000-0000-4000-8000-000000000001/app_loja/50000000-0000-4000-8000-000000000001.png",
      "state": "active",
      "revision": "20000000-0000-4000-8000-000000000001",
      "contentType": "image/png",
      "byteSize": 68,
      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "createdAt": "2026-10-19T20:00:00Z",
      "updatedAt": "2026-10-19T20:00:00Z"
    },
    "revision": "20000000-0000-4000-8000-000000000001"
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 409, 412, 413, 415, 422, 428, 429, 500, 503. Veja códigos e repetição.

DELETE /apps/{appId}/logo

Consultar, associar e remover logo via ativo autorizado.

Permissão: apps:update. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`appId`	path	sim	OpaqueId
`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.
`If-Match`	header	sim	ETag forte obtido em consulta. Ausência 428; revisão antiga 412.

Sem corpo de requisição.

Resposta: 204. Logo padrão desvinculado; arquivo preservado. Corpo vazio.

Sem corpo de resposta.

Erros previstos: 400, 401, 403, 404, 409, 412, 413, 422, 428, 429, 500, 503. Veja códigos e repetição.

POST /links/{linkId}/duplicate

Criar novo link a partir de configuração existente.

Permissão: links:create. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`linkId`	path	sim	LinkId
`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.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição
`slug`	string	sim	Máximo 200 caracteres
`prefix`	string	não	Máximo 200 caracteres
`domain`	Domain	não	Consulte o schema para restrições e campos internos
`title`	string / null	não	Consulte o schema para restrições e campos internos

{
  "slug": "tenis-copia"
}

Resposta: 201. Criado. Exemplo fictício.

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

Erros previstos: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503. Veja códigos e repetição.

POST /links/validate

Validar entrada e indicar conflitos conhecidos sem reservar endereço.

Permissão: links:validate. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`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.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição
`appId`	string	sim	Máximo 500 caracteres
`domain`	Domain	sim	Consulte o schema para restrições e campos internos
`prefix`	string	não	Máximo 200 caracteres
`slug`	string	sim	Máximo 200 caracteres
`folderId`	string / null	não	Consulte o schema para restrições e campos internos
`campaignId`	string / null	não	Consulte o schema para restrições e campos internos
`lifecycle`	LinkLifecycle	não	Consulte o schema para restrições e campos internos
`utm`	UtmParameters	não	Consulte o schema para restrições e campos internos
`title`	string / null	não	Consulte o schema para restrições e campos internos
`description`	string / null	não	Consulte o schema para restrições e campos internos
`imageUrl`	string / null	não	Consulte o schema para restrições e campos internos
`desktopUrl`	string / null	não	Consulte o schema para restrições e campos internos
`playStoreUrl`	string / null	não	Consulte o schema para restrições e campos internos
`appStoreUrl`	string / null	não	Consulte o schema para restrições e campos internos
`appPath`	string / null	não	Consulte o schema para restrições e campos internos
`parameters`	Parameters	não	Consulte o schema para restrições e campos internos
`webOnly`	boolean	não	Consulte o schema para restrições e campos internos
`behavior`	—	não	Valores: manual, automatic, intelligent
`group`	—	não	Valores: main, operational
`templateData`	object	não	Consulte o schema para restrições e campos internos
`templateSelection`	object	não	Consulte o schema para restrições e campos internos

{
  "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: 200. Sucesso. Exemplo fictício.

{
  "data": {
    "valid": true,
    "available": true,
    "normalized": {
      "appId": "app_loja",
      "domain": "go.example.com",
      "prefix": "ofertas",
      "slug": "tenis",
      "title": "Tênis",
      "desktopUrl": "https://shop.example.com/"
    }
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503. Veja códigos e repetição.

GET /links/availability

Consultar disponibilidade de domínio/prefixo/slug autorizado.

Permissão: links:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`appId`	query	sim	AppId
`domain`	query	sim	Domain
`prefix`	query	não	string
`slug`	query	sim	string

Sem corpo de requisição.

Resposta: 200. Sucesso. Exemplo fictício.

{
  "data": {
    "appId": "app_loja",
    "domain": "go.example.com",
    "prefix": "ofertas",
    "slug": "tenis",
    "available": true
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

POST /links/{linkId}/preview

Simular destino por cenário sem gerar clique nem fazer redirect.

Permissão: links:preview. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`linkId`	path	sim	LinkId
`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.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição
`at`	AnalyticsInstant	não	Consulte o schema para restrições e campos internos
`country`	string	não	Consulte o schema para restrições e campos internos
`platform`	—	sim	Valores: desktop, android, ios
`source`	—	não	Valores: browser, social

{
  "platform": "android",
  "source": "browser"
}

Resposta: 200. Sucesso. Exemplo fictício.

{
  "data": {
    "state": "active",
    "allowed": true,
    "matchedRuleId": null,
    "evaluatedAt": "2026-10-19T20:00:00Z",
    "linkId": "go.example.com~-ofertas~-tenis",
    "appId": "app_loja",
    "platform": "android",
    "mode": "android",
    "nativeUrl": "loja://produtos/tenis",
    "fallbackUrl": "https://shop.example.com/",
    "opening": "manual",
    "publication": {
      "status": "pending",
      "desiredRevision": "20000000-0000-4000-8000-000000000001",
      "confirmedRevision": null,
      "updatedAt": "2026-10-19T20:00:00Z"
    },
    "sideEffects": false
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503. Veja códigos e repetição.

GET /links/{linkId}/publication

Consultar revisão desejada/confirmada e estado de sincronização.

Permissão: links:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`linkId`	path	sim	LinkId

Sem corpo de requisição.

Resposta: 200. Sucesso. Exemplo fictício.

{
  "data": {
    "linkId": "go.example.com~-ofertas~-tenis",
    "appId": "app_loja",
    "revision": "20000000-0000-4000-8000-000000000001",
    "status": "pending",
    "desiredRevision": "20000000-0000-4000-8000-000000000001",
    "confirmedRevision": null,
    "updatedAt": "2026-10-19T20:00:00Z"
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

POST /links/{linkId}/resync

Solicitar ressincronização via outbox.

Permissão: links:resync. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`linkId`	path	sim	LinkId
`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.
`If-Match`	header	sim	ETag forte obtido em consulta. Ausência 428; revisão antiga 412.

Corpo: application/json. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição

{}

Resposta: 202. Sucesso. Exemplo fictício.

{
  "data": {
    "linkId": "go.example.com~-ofertas~-tenis",
    "appId": "app_loja",
    "revision": "20000000-0000-4000-8000-000000000001",
    "status": "pending",
    "desiredRevision": "20000000-0000-4000-8000-000000000001",
    "confirmedRevision": null,
    "updatedAt": "2026-10-19T20:00:00Z"
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 409, 412, 413, 415, 422, 428, 429, 500, 503. Veja códigos e repetição.

GET /assets

Listar e fazer upload de ativos autorizados.

Permissão: assets:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`appId`	query	sim	AppId
`state`	query	não	AssetStateFilter
`limit`	query	não	integer
`cursor`	query	não	Cursor

Sem corpo de requisição.

Resposta: 200. Sucesso. Exemplo fictício.

{
  "data": [
    {
      "id": "50000000-0000-4000-8000-000000000001",
      "appId": "app_loja",
      "url": "https://images.staging.agilink.io/40000000-0000-4000-8000-000000000001/app_loja/50000000-0000-4000-8000-000000000001.png",
      "state": "active",
      "revision": "20000000-0000-4000-8000-000000000001",
      "contentType": "image/png",
      "byteSize": 68,
      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "createdAt": "2026-10-19T20:00:00Z",
      "updatedAt": "2026-10-19T20:00:00Z"
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

POST /assets

Listar e fazer upload de ativos autorizados.

Permissão: assets:create. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`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.

Corpo: multipart/form-data. Campos desconhecidos são rejeitados.

Campo	Tipo	Obrigatório	Restrição
`appId`	AppId	sim	Consulte o schema para restrições e campos internos
`file`	string	sim	Consulte o schema para restrições e campos internos

Envie appId como texto e file como bytes de PNG/JPEG; o cliente deve gerar o boundary. Não envie o placeholder abaixo como arquivo.

{
  "appId": "app_loja",
  "file": "<bytes do arquivo PNG ou JPEG>"
}

Resposta: 201. Criado. Exemplo fictício.

{
  "data": {
    "id": "50000000-0000-4000-8000-000000000001",
    "appId": "app_loja",
    "url": "https://images.staging.agilink.io/40000000-0000-4000-8000-000000000001/app_loja/50000000-0000-4000-8000-000000000001.png",
    "state": "active",
    "revision": "20000000-0000-4000-8000-000000000001",
    "contentType": "image/png",
    "byteSize": 68,
    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-10-19T20:00:00Z",
    "updatedAt": "2026-10-19T20:00:00Z"
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 409, 413, 415, 422, 429, 500, 503. Veja códigos e repetição.

GET /assets/{assetId}

Metadados e exclusão condicionada a referências.

Permissão: assets:read. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`assetId`	path	sim	OpaqueId

Sem corpo de requisição.

Resposta: 200. Sucesso. Exemplo fictício.

{
  "data": {
    "id": "50000000-0000-4000-8000-000000000001",
    "appId": "app_loja",
    "url": "https://images.staging.agilink.io/40000000-0000-4000-8000-000000000001/app_loja/50000000-0000-4000-8000-000000000001.png",
    "state": "active",
    "revision": "20000000-0000-4000-8000-000000000001",
    "contentType": "image/png",
    "byteSize": 68,
    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "createdAt": "2026-10-19T20:00:00Z",
    "updatedAt": "2026-10-19T20:00:00Z"
  },
  "meta": {
    "requestId": "req_00000000000040008000000000000001"
  }
}

Erros previstos: 400, 401, 403, 404, 422, 429, 500, 503. Veja códigos e repetição.

DELETE /assets/{assetId}

Metadados e exclusão condicionada a referências.

Permissão: assets:delete. Credencial: sessão humana ou chave de API com acesso ao aplicativo.

Parâmetro	Local	Obrigatório	Significado
`assetId`	path	sim	OpaqueId
`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.
`If-Match`	header	sim	ETag forte obtido em consulta. Ausência 428; revisão antiga 412.

Sem corpo de requisição.

Resposta: 204. Bytes removidos do R2 e ativo marcado como deleted. Corpo vazio.

Sem corpo de resposta.

Erros previstos: 400, 401, 403, 404, 409, 412, 413, 422, 428, 429, 500, 503. Veja códigos e repetição.