Synupv1
Criar chave
v1Recursos/Dados

Dados

A biblioteca de assets unificada por trás da aba Dados: o catálogo paginado multi-origem (uploads, imagens geradas, mídia sincronizada, fotos importadas do GBP, mídia enviada por usuários), pastas e o vocabulário de tags de assets. Distinto das tags de agrupamento de locais de locations/tags.

Retorna todas as tags de mídia definidas na sua agência.

Listar tags de mídia

get/api/v1/tags
media:read
Resposta
dataobjectopcional
tagsarray of objectopcional
As tags de mídia da agência.
idstringopcional
namestringopcional
Erros
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
get/api/v1/tags
Sua chave de API
{
  "data": {
    "tags": [
      {
        "id": "tag_1",
        "name": "VIP"
      },
      {
        "id": "tag_2",
        "name": "Seasonal"
      }
    ]
  }
}
v1Recursos/Dados/postCriar uma tag de mídia

Cria uma nova tag de mídia com o nome informado.

Criar uma tag de mídia

post/api/v1/tags
media:write
Corpo da solicitação
namestringobrigatório
O nome da tag.
Resposta
dataobjectopcional
idstringopcional
Identificador único da tag recém-criada.
namestringopcional
O nome da tag.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
post/api/v1/tags
Sua chave de API
Corpo da solicitação*
{
  "data": {
    "id": "tag_1",
    "name": "VIP"
  }
}
v1Recursos/Dados/patchRenomear uma tag de asset

Renomeia uma tag. Se outra tag já tiver o nome de destino, as duas são mescladas: todo asset marcado com qualquer uma delas passa a ficar marcado com o nome que permanece.

Renomear uma tag de asset

patch/api/v1/tags/{id}
media:write
Parâmetros de consulta
idstringobrigatório
A tag a ser renomeada.
Corpo da solicitação
namestringobrigatório
O novo nome da tag. Obrigatório.
Resposta
dataobjectopcional
idstringopcional
Identificador único da tag recém-criada.
namestringopcional
O nome da tag.
countnumberopcional
O número de assets que agora carregam esta tag.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
patch/api/v1/tags/{id}
Sua chave de API
id *
Corpo da solicitação*
{
  "data": {
    "id": "tag_1",
    "name": "VIP Clients",
    "count": 12
  }
}
v1Recursos/Dados/deleteExcluir uma tag de mídia

Exclui uma tag de mídia. Isso não exclui os arquivos aos quais ela estava associada. assetsUntagged na resposta informa quantos arquivos perderam a tag.

Excluir uma tag de mídia

delete/api/v1/tags/{id}
media:write
Parâmetros de consulta
idstringobrigatório
ID da tag de mídia a ser excluída.
Resposta
dataobjectopcional
assetsUntaggednumberopcional
Número de arquivos que tinham esta tag — todos perderam a associação quando a tag foi excluída.
Erros
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
delete/api/v1/tags/{id}
Sua chave de API
id *
{
  "data": {
    "assetsUntagged": 5
  }
}
v1Recursos/Dados/postAdicionar arquivos a uma tag

Associa um ou mais arquivos, pela chave, a uma tag de mídia existente.

Adicionar arquivos a uma tag

post/api/v1/tags/{id}/assets
media:write
Parâmetros de consulta
idstringobrigatório
ID da tag de mídia.
Corpo da solicitação
assetKeysarray of stringobrigatório
Chaves dos arquivos a serem associados a esta tag.
Resposta
dataobjectopcional
addedarray of stringopcional
Chaves dos arquivos realmente associados — um arquivo que já possui esta tag não é duplicado.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
post/api/v1/tags/{id}/assets
Sua chave de API
id *
Corpo da solicitação*
{
  "data": {
    "added": [
      "upload:abc123",
      "gmb:xyz789"
    ]
  }
}
v1Recursos/Dados/deleteRemover um arquivo de uma tag

Desassocia um único arquivo, pela chave, de uma tag de mídia.

Remover um arquivo de uma tag

delete/api/v1/tags/{id}/assets
media:write
Parâmetros de consulta
idstringobrigatório
ID da tag de mídia.
assetKeystringobrigatório
Chave do arquivo a ser removido desta tag.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
delete/api/v1/tags/{id}/assets
Sua chave de API
id *
assetKey *
{}
v1Recursos/Dados/getListar assets

Retorna um trecho paginado do catálogo unificado de assets, do mais recente ao mais antigo — uploads, imagens geradas por IA, assets da biblioteca de mídia sincronizada, fotos importadas do GBP e mídia enviada por usuários (UGC), combinados em um único feed.

Listar assets

get/api/v1/assets
media:read
Parâmetros de consulta
sourcestring (all | upload | gmb | generated | discovered | ugc)opcional
Restringir a uma aba de origem: all (padrão), upload, gmb, generated, discovered ou ugc.
typestringopcional
Restringir a um tipo de asset, por exemplo image ou video.
folderIdstringopcional
Restringir a assets desta pasta.
tagstringopcional
Restringir a assets com este nome de tag.
locationIdstringopcional
Restringir a assets atribuídos a este local. Procure com GET /api/v1/locations.
clientIdstringopcional
O cliente ao qual restringir os resultados. Obrigatório se esta chave for restrita a clientes específicos e nenhum locationId for informado. Procure com GET /api/v1/clients.
qstringopcional
Buscar por título ou nome de arquivo.
cursorstringopcional
Cursor de paginação do nextCursor de uma resposta anterior.
limitnumberopcional
Máximo de itens a retornar. Padrão 60, máximo 200.
statusstring (needs_review | spam | ok | skipped)opcional
Filtro de status de moderação — só se aplica quando source é ugc: needs_review, spam, ok ou skipped.
Resposta
dataobjectopcional
itemsarray of objectopcional
A página de assets.
keystringopcional
Identificador composto do arquivo, no formato "<source>:<id>".
sourcestringopcional
Origem deste arquivo (ex.: um envio do OS em vez de uma fonte importada).
idstringopcional
O id do arquivo dentro de sua fonte.
titlestringopcional
O título do arquivo.
filenamestringopcional
O nome de arquivo original do arquivo.
mimestringopcional
O tipo MIME do arquivo.
kindstringopcional
O tipo do arquivo (foto ou vídeo).
sizeBytesnumberopcional
Tamanho do arquivo em bytes, ou null se desconhecido.
urlstringopcional
URL pronta para uso com os bytes do arquivo.
thumbnailUrlstringopcional
URL de uma miniatura de pré-visualização, ou null.
tagsarray of stringopcional
Tags associadas ao arquivo.
folderIdsarray of stringopcional
Pastas de arquivos às quais este arquivo pertence.
locationIdsarray of stringopcional
Todos os locais associados a este arquivo.
nextCursorstringopcional
Passe como cursor na próxima chamada para buscar a página seguinte. Null quando não há mais páginas.
countsobjectopcional
Totais por aba (all/upload/gmb/generated/discovered/ugc), independentes dos filtros ativos.
Erros
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
get/api/v1/assets
Sua chave de API
source
type
folderId
tag
locationId
clientId
q
cursor
limit
status
{
  "data": {
    "items": [
      {
        "key": "upload:abc123",
        "source": "upload",
        "id": "abc123",
        "title": "Storefront photo",
        "filename": "storefront.jpg",
        "mime": "image/jpeg",
        "kind": "image",
        "sizeBytes": 482913,
        "url": "https://cdn.synup.com/media/abc123.jpg",
        "thumbnailUrl": "https://cdn.synup.com/media/abc123-thumb.jpg",
        "tags": [
          "VIP"
        ],
        "folderIds": [
          "folder_1"
        ],
        "locationIds": [
          "loc_456"
        ]
      }
    ],
    "nextCursor": null,
    "counts": {
      "all": 1,
      "upload": 1,
      "gmb": 0,
      "generated": 0,
      "discovered": 0,
      "ugc": 0
    }
  }
}
v1Recursos/Dados/getListar pastas

Retorna todas as pastas desta agência, com sua contagem de itens e mistura de origens.

Listar pastas

get/api/v1/folders
media:read
Parâmetros de consulta
scopeTypestring (account | client | location | brand)opcional
Restringir a pastas com este escopo: account, client, location ou brand.
scopeIdstringopcional
Restringir a pastas com este id de escopo. Requer scopeType.
Resposta
dataobjectopcional
itemsarray of objectopcional
idstringopcional
Identificador único da pasta.
namestringopcional
O nome da pasta.
descriptionstringopcional
A descrição da pasta, ou null.
itemCountnumberopcional
Número de assets atualmente na pasta.
sourceMixarray of stringopcional
As origens de assets distintas presentes na pasta.
scopeobjectopcional
O escopo da pasta, ou null quando vale para toda a agência.
typestring (account | client | location | brand)opcional
idstringopcional
sharingobjectopcional
O estado de compartilhamento público da pasta.
accessstring (restricted | link)opcional
urlstringopcional
createdAtstringopcional
Quando a pasta foi criada, como timestamp ISO 8601.
Erros
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
get/api/v1/folders
Sua chave de API
scopeType
scopeId
{
  "data": {
    "items": [
      {
        "id": "folder_1",
        "name": "Storefront Photos",
        "description": null,
        "itemCount": 12,
        "sourceMix": [
          "upload",
          "gmb"
        ],
        "scope": {
          "type": "client",
          "id": "cli_123"
        },
        "sharing": {
          "access": "restricted",
          "url": null
        },
        "createdAt": "2026-01-15T10:00:00.000Z"
      }
    ]
  }
}
v1Recursos/Dados/postCriar uma pasta

Cria uma nova pasta vazia. Adicione assets a ela com POST /api/v1/folders/{id}/items.

Criar uma pasta

post/api/v1/folders
media:write
Corpo da solicitação
namestringobrigatório
O nome da pasta. Obrigatório.
descriptionstringopcional
Uma descrição opcional.
scopeTypestring (account | client | location | brand)opcional
Escopo opcional: account, client, location ou brand. Pastas sem escopo valem para toda a agência.
scopeIdstringopcional
O id para scopeType, se informado.
Resposta
dataobjectopcional
folderobjectopcional
idstringopcional
Identificador único da pasta.
namestringopcional
O nome da pasta.
descriptionstringopcional
A descrição da pasta, ou null.
itemCountnumberopcional
Número de assets atualmente na pasta.
sourceMixarray of stringopcional
As origens de assets distintas presentes na pasta.
scopeobjectopcional
O escopo da pasta, ou null quando vale para toda a agência.
typestring (account | client | location | brand)opcional
idstringopcional
sharingobjectopcional
O estado de compartilhamento público da pasta.
accessstring (restricted | link)opcional
urlstringopcional
createdAtstringopcional
Quando a pasta foi criada, como timestamp ISO 8601.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
post/api/v1/folders
Sua chave de API
Corpo da solicitação*
{
  "data": {
    "folder": {
      "id": "folder_1",
      "name": "Storefront Photos",
      "description": null,
      "itemCount": 0,
      "sourceMix": [],
      "scope": null,
      "sharing": {
        "access": "restricted",
        "url": null
      },
      "createdAt": "2026-01-15T10:00:00.000Z"
    }
  }
}
v1Recursos/Dados/getObter uma pasta

Retorna o detalhe de uma pasta. Seu conteúdo: GET /api/v1/assets?folderId={id}.

Obter uma pasta

get/api/v1/folders/{id}
media:read
Parâmetros de consulta
idstringobrigatório
A pasta a consultar.
Resposta
dataobjectopcional
folderobjectopcional
idstringopcional
Identificador único da pasta.
namestringopcional
O nome da pasta.
descriptionstringopcional
A descrição da pasta, ou null.
itemCountnumberopcional
Número de assets atualmente na pasta.
sourceMixarray of stringopcional
As origens de assets distintas presentes na pasta.
scopeobjectopcional
O escopo da pasta, ou null quando vale para toda a agência.
typestring (account | client | location | brand)opcional
idstringopcional
sharingobjectopcional
O estado de compartilhamento público da pasta.
accessstring (restricted | link)opcional
urlstringopcional
createdAtstringopcional
Quando a pasta foi criada, como timestamp ISO 8601.
Erros
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
get/api/v1/folders/{id}
Sua chave de API
id *
{
  "data": {
    "folder": {
      "id": "folder_1",
      "name": "Storefront Photos",
      "description": null,
      "itemCount": 12,
      "sourceMix": [
        "upload",
        "gmb"
      ],
      "scope": {
        "type": "client",
        "id": "cli_123"
      },
      "sharing": {
        "access": "restricted",
        "url": null
      },
      "createdAt": "2026-01-15T10:00:00.000Z"
    }
  }
}
v1Recursos/Dados/patchAtualizar uma pasta

Renomeia uma pasta ou edita sua descrição ou escopo.

Atualizar uma pasta

patch/api/v1/folders/{id}
media:write
Parâmetros de consulta
idstringobrigatório
A pasta a atualizar.
Corpo da solicitação
namestringopcional
Novo nome.
descriptionstringopcional
Nova descrição, ou null para removê-la.
scopeTypestring (account | client | location | brand)opcional
Novo tipo de escopo: account, client, location ou brand.
scopeIdstringopcional
O id para scopeType, se informado.
Resposta
dataobjectopcional
folderobjectopcional
idstringopcional
Identificador único da pasta.
namestringopcional
O nome da pasta.
descriptionstringopcional
A descrição da pasta, ou null.
itemCountnumberopcional
Número de assets atualmente na pasta.
sourceMixarray of stringopcional
As origens de assets distintas presentes na pasta.
scopeobjectopcional
O escopo da pasta, ou null quando vale para toda a agência.
typestring (account | client | location | brand)opcional
idstringopcional
sharingobjectopcional
O estado de compartilhamento público da pasta.
accessstring (restricted | link)opcional
urlstringopcional
createdAtstringopcional
Quando a pasta foi criada, como timestamp ISO 8601.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
patch/api/v1/folders/{id}
Sua chave de API
id *
Corpo da solicitação
{
  "data": {
    "folder": {
      "id": "folder_1",
      "name": "Storefront Photos (2026)",
      "description": "Current-season storefront shots",
      "itemCount": 12,
      "sourceMix": [
        "upload",
        "gmb"
      ],
      "scope": {
        "type": "client",
        "id": "cli_123"
      },
      "sharing": {
        "access": "restricted",
        "url": null
      },
      "createdAt": "2026-01-15T10:00:00.000Z"
    }
  }
}
v1Recursos/Dados/deleteExcluir uma pasta

Exclui a pasta. Seus assets não são afetados — apenas perdem a associação à pasta. itemsRemoved e shareLinksRevoked na resposta informam quantas coisas foram removidas silenciosamente junto com ela.

Excluir uma pasta

delete/api/v1/folders/{id}
media:write
Parâmetros de consulta
idstringobrigatório
A pasta a excluir.
Resposta
dataobjectopcional
itemsRemovednumberopcional
Número de itens (assets) removidos da pasta — essa quantidade de atribuições de FolderItem foi excluída junto com ela.
shareLinksRevokednumberopcional
Número de links de compartilhamento ativos desta pasta que foram revogados ao excluí-la.
Erros
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
delete/api/v1/folders/{id}
Sua chave de API
id *
{
  "data": {
    "itemsRemoved": 12,
    "shareLinksRevoked": 1
  }
}
v1Recursos/Dados/postCompartilhar uma pasta

Emite (ou renova) um link público para a pasta. Renovar revoga qualquer link emitido antes.

Compartilhar uma pasta

post/api/v1/folders/{id}/share
media:write
Parâmetros de consulta
idstringobrigatório
A pasta a compartilhar.
Resposta
dataobjectopcional
urlstringopcional
A URL pública de compartilhamento.
accessstring (link)opcional
Sempre "link" em caso de sucesso.
Erros
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
post/api/v1/folders/{id}/share
Sua chave de API
id *
{
  "data": {
    "url": "https://synup.com/s/aB3dE9fGhJ",
    "access": "link"
  }
}
v1Recursos/Dados/deleteDeixar de compartilhar uma pasta

Revoga o link público da pasta.

Deixar de compartilhar uma pasta

delete/api/v1/folders/{id}/share
media:write
Parâmetros de consulta
idstringobrigatório
A pasta cujo compartilhamento será revogado.
Resposta
dataobjectopcional
accessstring (restricted)opcional
Sempre "restricted" em caso de sucesso.
Erros
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
delete/api/v1/folders/{id}/share
Sua chave de API
id *
{
  "data": {
    "access": "restricted"
  }
}
v1Recursos/Dados/postAdicionar assets a uma pasta

Adiciona cada chave de asset informada à pasta. Chaves já presentes são ignoradas.

Adicionar assets a uma pasta

post/api/v1/folders/{id}/items
media:write
Parâmetros de consulta
idstringobrigatório
A pasta à qual adicionar assets.
Corpo da solicitação
assetKeysarray of stringobrigatório
Chaves de asset opacas "<source>:<id>" a adicionar. Obrigatório, não vazio.
Resposta
dataobjectopcional
idstringopcional
itemCountnumberopcional
A contagem de itens da pasta após a alteração.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
post/api/v1/folders/{id}/items
Sua chave de API
id *
Corpo da solicitação*
{
  "data": {
    "id": "folder_1",
    "itemCount": 13
  }
}
v1Recursos/Dados/deleteRemover um asset de uma pasta

Remove a associação de um asset à pasta. Sucesso sem efeito se ele não era membro.

Remover um asset de uma pasta

delete/api/v1/folders/{id}/items
media:write
Parâmetros de consulta
idstringobrigatório
A pasta da qual remover o asset.
assetKeystringobrigatório
A chave de asset opaca "<source>:<id>" a remover. Passada como parâmetro de consulta (codifique os dois-pontos), não como segmento de caminho.
Resposta
dataobjectopcional
idstringopcional
itemCountnumberopcional
A contagem de itens da pasta após a alteração.
Erros
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
delete/api/v1/folders/{id}/items
Sua chave de API
id *
assetKey *
{
  "data": {
    "id": "folder_1",
    "itemCount": 12
  }
}