Envie os dados da sua empresa

Onde isso se encaixa

O envio permite que a Kaleidr responda com base nos dados da sua organização. É um recurso Enterprise. Uma versão publicada é utilizada pelo assistente do Kaleidr Studio para membros autenticados. Para utilizá-la no seu site ou backend, são necessários mais três passos: criar uma chave com permissão de leitura, fazer uma pergunta com ela e verificar se seus locais aparecem na resposta. Respostas com seus próprios dados explica o processo completo. Esta página é a referência para envio: requisições, campos, limites, erros e retirada de versões.

Esta página não trata dos arquivos adicionados ao painel Data de um mapa no Studio, como planilhas, GeoJSON ou GPX. Esse recurso é separado e está disponível em todos os planos: consulte Conjuntos de dados no mapa.

Há dois modos de envio, ambos usando o mesmo processamento:

• Pela interface: a seção Data for AI Answers na parte inferior do painel Data de qualquer mapa no Kaleidr Studio. É a única tela de upload; seus controles aparecem somente para proprietário ou administrador de uma organização habilitada. Veja Envio pelo Studio.
• Pela API nesta página: a tela utiliza os mesmos endpoints. Todos os formatos, limites, estados e erros se aplicam aos dois caminhos, e uma versão criada por um aparece no outro.

Três propriedades importantes antes de enviar:

• Os dados são consultados quando uma pergunta é respondida. Kaleidr consulta a versão publicada naquele momento; cancelar sua publicação impede imediatamente que respostas futuras usem seus dados.
• Os dados são servidos apenas à sua organização. São isolados por organização e não aparecem nas respostas do mapa para consumidores nem de outras organizações.
• Os valores nunca são inventados. Um assistente opcional propõe a associação de colunas usando o cabeçalho e até cinco linhas de exemplo. Todas as linhas são transformadas pela associação que você aprovar. Corrija e execute novamente uma associação incorreta; preços, datas e nomes não são gerados.

Disponibilidade

Requisito	Detalhes
Plano	Enterprise. Em Free e Pro, upload, publicação, novo processamento e proposta de mapeamento retornam 403 vendor_data_not_on_plan. Vale o plano da organização em kaleidr.com/billing, não um plano separado do Studio.
Função	Proprietário ou administrador da organização; outros recebem 403 org_admin_required.
Limites	Definidos no contrato da organização; veja Limites. GET /shared-api/datahub/limits retorna os valores vigentes. Referência
Interface	Data for AI Answers no painel Data do Kaleidr Studio ou a API desta página. Ambas passam pelas mesmas verificações.

Quais chamadas exigem qual plano:

Chamadas	Função	Plano
Propor mapeamento, enviar, publicar, reiniciar processamento	Proprietário ou administrador	Enterprise
Ler limites, estado de ingestão e lista de versões	Proprietário ou administrador	Qualquer
Despublicar ou excluir versão	Proprietário ou administrador	Qualquer

As duas últimas linhas continuam disponíveis em todos os planos, permitindo que uma organização que deixe o Enterprise veja o material enviado e o retire.

O uso dos dados também é exclusivo do Enterprise, em ambos os ambientes. O assistente do Studio consulta a versão publicada apenas enquanto a organização estiver no Enterprise. Para respostas pela API ou SDK é necessária a permissão vendor, disponível apenas para Enterprise. Veja Respostas com seus próprios dados.

O que a seção Data for AI Answers mostra depende do plano e da função da pessoa: consulte O que a seção mostra quando você não pode enviar dados.

O que sua organização pode enviar

Consulte os limites antes do envio. É essa chamada que a seção do Studio faz ao abrir.

Requisição	GET /shared-api/datahub/limits
Quem	Proprietário ou administrador, qualquer plano
Consulta	org_id, opcional, se você administra várias organizações

curl https://api.kaleidr.com/shared-api/datahub/limits \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

Para uma organização Enterprise, os três limites são definidos no contrato e por isso não há valores fixos no exemplo. limits sempre contém os três campos inteiros da tabela abaixo.

{
  "can_upload": true,
  "plan": "enterprise",
  "limits": { "…": "places, documents and artifact_mb: three integers, described below" },
  "reason": null
}

Em Free e Pro a chamada ainda retorna 200, com a justificativa:

{
  "can_upload": false,
  "plan": "pro",
  "limits": { "places": 0, "documents": 0, "artifact_mb": 0 },
  "reason": "vendor_data_not_on_plan"
}

Campo	Tipo	Significado
can_upload	boolean	Se o envio é permitido para a organização.
plan	string ou null	Plano: free, pro ou enterprise.
limits.places	integer	Locais por envio; em CSV, linhas de dados.
limits.documents	integer	Documentos por envio.
limits.artifact_mb	integer	Tamanho do arquivo em MiB.
reason	string ou null	vendor_data_not_on_plan quando can_upload é false; caso contrário, null. Todos os limites ficam em 0 quando não permitido.

Esses números são específicos da sua organização e definidos em seu contrato. Nenhum limite pode ultrapassar o máximo que um upload pode aceitar: a plataforma impõe um teto próprio a cada uma das três medidas, e o contrato não pode excedê-lo.

Status	Significado
200	Sempre para proprietário ou administrador em qualquer plano. Abaixo de Enterprise retorna can_upload: false em vez de recusar.
401	Token de acesso ausente, expirado ou não é um access token.
403 org_admin_required	A conta não é proprietária nem administradora da organização.

Autenticação

Toda chamada usa como bearer o token de acesso da sua conta Kaleidr autenticada:

Authorization: Bearer <account access token>

• Não é uma chave de API. Uma chave kld_pk_… ou kld_sk_… é recusada. Chaves identificam integrações; o envio exige autenticação como pessoa com função administrativa.
• Deve ser o token de acesso, não o ID token.
• Pertence a um proprietário ou administrador autenticado e expira com a sessão. Ainda não há credencial de longa duração; para automatizar uploads, fale com a Kaleidr antes de implementar.
• A interface do Studio usa automaticamente a sessão da pessoa conectada.

Todos os caminhos desta página usam https://api.kaleidr.com. Os exemplos obtêm o token de uma variável de ambiente:

export KALEIDR_ACCESS_TOKEN='<account access token>'

Se você administra várias organizações, passe org_id (no corpo do upload ou como parâmetro ?org_id= nas demais requisições). Se omitido, usa-se a organização principal.

O que pode ser enviado

Cada envio contém um arquivo de texto, passado como string em uma requisição JSON. A extensão do nome determina o parser.

Você tem	Envie	Contém
Lista de locais	.csv com nomes de colunas fixos, sem mapeamento	Locais
Exportação com uma linha por diária, quarto ou tarifa	.csv com mapping_spec	Locais, tipos de quarto, planos tarifários, tarifas diárias e disponibilidade
Tudo já estruturado	Pacote .json	Todos esses dados, além de horários de funcionamento e documentos

Cada upload deve incluir pelo menos um local.

CSV de locais

O cabeçalho utiliza os seguintes nomes de coluna:

Coluna	Obrigatória	Observações
name	Sim	Linha sem nome falha e é informada pelo número.
timezone	Sim	Fuso IANA, como Europe/London.
lat, lng	Uma das duas formas	Coordenadas usadas exatamente como fornecidas.
address	Uma das duas formas	Usado para localizar coordenadas quando lat e lng faltam.
category	Não	Rótulo curto, como hotel ou restaurant.
ref	Não	Seu identificador. Sem ele, utiliza-se o número da linha.

name,timezone,lat,lng,address,category
Harbor Hotel,Europe/London,51.5079,-0.0877,"1 Example Street, London",hotel
Canal House,Europe/Amsterdam,,,"Example Gracht 12, Amsterdam",hotel

Planilha com mapeamento de colunas

Uma planilha com uma linha por observação (propriedade, quarto, plano, data ou preço) não pode ser interpretada apenas por colunas fixas. Envie um mapping_spec informando a origem de cada campo.

Property,Address,Room,Plan,Date,Nightly Rate,Available
Harbor Hotel,"1 Example Street, London",Double,Flexible,2026-11-06,189.00,4
Harbor Hotel,"1 Example Street, London",Suite,Flexible,2026-11-06,320.00,1

{
  "places": {
    "ref_from": ["Property"],
    "fields": {
      "name": "Property",
      "address": "Address",
      "timezone": { "const": "Europe/London" },
      "category": { "const": "hotel" }
    }
  },
  "room_types": { "ref_from": ["Room"], "fields": { "name": "Room" } },
  "rate_plans": { "ref_from": ["Plan"], "fields": { "name": "Plan" } },
  "daily_rates": {
    "fields": {
      "stay_date": "Date",
      "price_amount": "Nightly Rate",
      "price_currency": { "const": "GBP" }
    }
  },
  "daily_inventory": {
    "fields": { "stay_date": "Date", "units_available": "Available" }
  }
}

Regras do mapeamento:

Parte	Significado
Seções	places (obrigatória), room_types, rate_plans, daily_rates, daily_inventory. Inclua apenas as presentes na planilha.
ref_from	Colunas que identificam um item. Linhas com valores idênticos nessas colunas representam o mesmo local, tipo de quarto ou plano.
fields	Cada campo aponta para uma coluna. Alguns aceitam uma constante na forma { "const": "value" }.

Um mapeamento só pode definir os campos a seguir. A última coluna indica quais aceitam constantes.

Seção	Campos configuráveis	Podem ser constantes
places	name, address, timezone, category, lat, lng, overture_id	timezone, category
room_types	name	name
rate_plans	name, currency, cancellation_policy, board_basis	name, currency
daily_rates	stay_date, price_amount, price_currency	price_currency
daily_inventory	stay_date, units_available	Nenhum

Duas regras importantes; violá-las causa erro de validação:

• Campos fora da tabela são recusados. O erro identifica o campo e os permitidos, por exemplo room_types.fields.beds: not a field a mapping can set -- room_types takes name. Informações como número de camas ou atributos livres devem ser enviadas por um pacote JSON.
• Constantes são recusadas nos demais campos. Preços, datas, contagens, nomes e posições devem vir de colunas: daily_rates.fields.price_amount: must name a column -- a constant cannot supply this field. Constantes servem para valores iguais em toda a planilha, como fuso ou moeda.

Os erros aparecem na lista errors de uma proposta e em error_report ao processar o upload. A ingestão falha e nada é preparado.

Se daily_rates estiver presente, room_types e rate_plans também devem estar, pois cada tarifa pertence a ambos. Se não houver coluna de plano, use uma constante para o nome.

O mapeamento só vale para .csv. Enviar um com .json faz a ingestão falhar.

Pacote JSON

Um arquivo .json contém um objeto com as listas a seguir. Os itens se referenciam por ref.

{
  "places": [
    {
      "ref": "harbor",
      "name": "Harbor Hotel",
      "timezone": "Europe/London",
      "lat": 51.5079,
      "lng": -0.0877,
      "address": "1 Example Street, London",
      "category": "hotel"
    }
  ],
  "room_types": [{ "ref": "double", "place_ref": "harbor", "name": "Double" }],
  "rate_plans": [{ "ref": "flex", "place_ref": "harbor", "name": "Flexible" }],
  "daily_rates": [
    {
      "place_ref": "harbor",
      "room_type_ref": "double",
      "rate_plan_ref": "flex",
      "stay_date": "2026-11-06",
      "price_amount": 189.0,
      "price_currency": "GBP"
    }
  ],
  "daily_inventory": [
    { "place_ref": "harbor", "room_type_ref": "double", "stay_date": "2026-11-06", "units_available": 4 }
  ],
  "hours": [
    { "place_ref": "harbor", "weekday": 0, "opens": "07:00", "closes": "23:00" },
    { "place_ref": "harbor", "valid_from": "2026-12-25", "valid_through": "2026-12-25", "is_closed": true }
  ],
  "documents": [
    { "title": "Cancellation policy", "text": "Free cancellation until 18:00 on the day before arrival." }
  ]
}

Lista	Campos obrigatórios	Observações
places	name, timezone e lat com lng ou address	ref único; pelo menos um local.
room_types, rate_plans	place_ref, name	ref único dentro da lista.
daily_rates	place_ref, room_type_ref, rate_plan_ref, stay_date, price_amount, price_currency
daily_inventory	place_ref, room_type_ref, stay_date, units_available
hours	place_ref e weekday ou data valid_from	weekday de 0 a 6, sendo 0 segunda-feira. opens e closes são horários.
documents	title, text	Somente texto embutido.

As listas também aceitam campos opcionais com limites de tamanho: veja Limites de campo.

Sobre documentos:

• Um documento contém title e text diretamente. Qualquer caminho ou chave de armazenamento é ignorado; o documento não pode apontar para um arquivo.
• O campo opcional mime descreve o texto. São preservados text/plain, text/markdown e text/html; outros valores viram text/plain.

Números precisam ser finitos. NaN e Infinity não são aceitos como coordenadas, preços, contagens ou dentro de JSON livre; a linha é registrada como erro.

Fluxo de envio

Um envio gera uma ingest (tarefa) e uma release (resultado versionado). A versão permanece draft até ser publicada. A publicação substitui a anterior atomicamente, sem atualização parcial nem intervalo sem dados. Para não ter nenhuma versão publicada, é necessário despublicar a atual.

propose a mapping  ─►  stage a preview  ─►  check the result  ─►  publish
   (optional,            POST /ingests        GET /ingests/{id}     POST /ingests/{id}/publish
    for a sheet)         preview: true

later, to take a release back out:   unpublish  ─►  delete
                                      POST /releases/{id}/unpublish    DELETE /releases/{id}

1. Proponha um mapeamento (opcional)

Use quando você tem uma planilha sem mapeamento. Envie somente o início do arquivo: cabeçalho e algumas linhas, não a exportação inteira.

Requisição	POST /inference-api/vendor/mapping/propose
Quem	Proprietário ou administrador de organização Enterprise.
Corpo	{ "csv_head": "<the first characters of your file>" }
Limite	csv_head entre 1 e 16.384 caracteres; 30 propostas por conta por hora.
Custo	Cada proposta consome créditos de IA pelos tokens utilizados; demais chamadas desta página não consomem créditos.

curl -X POST https://api.kaleidr.com/inference-api/vendor/mapping/propose \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"csv_head":"Property,Address,Room,Plan,Date,Nightly Rate,Available\nHarbor Hotel,\"1 Example Street, London\",Double,Flexible,2026-11-06,189.00,4\nHarbor Hotel,\"1 Example Street, London\",Suite,Flexible,2026-11-06,320.00,1\n"}'

{
  "mapping_spec": { "places": { "ref_from": ["Property"], "fields": { "name": "Property", "address": "Address", "timezone": { "const": "Europe/London" } } }, "room_types": { "ref_from": ["Room"], "fields": { "name": "Room" } } },
  "notes": "Time zone inferred from the addresses.",
  "columns": ["Property", "Address", "Room", "Plan", "Date", "Nightly Rate", "Available"],
  "sample_result": { "places": 1, "room_types": 2, "rate_plans": 1, "daily_rates": 2, "daily_inventory": 2 },
  "errors": []
}

Como interpretar a resposta:

• Confira sample_result. O mapeamento proposto é aplicado às linhas de exemplo, e sample_result mostra quantos itens resultaram por seção. Assim você detecta um mapeamento aparentemente correto que não produziu resultados.
• errors pode conter itens mesmo com 200. Uma proposta inválida retorna os problemas juntos para você corrigir: campos obrigatórios sem coluna, nomes inexistentes, fuso IANA inválido ou moeda com formato incorreto.
• Somente linhas completas são amostradas, no máximo cinco. A última linha de csv_head é descartada a menos que o texto termine com quebra de linha, pois pode estar incompleta.
• Nada é armazenado. Você pode editar a proposta e enviá-la depois.

Status	Significado
403 org_admin_required	A conta não administra nenhuma organização.
403 vendor_data_not_on_plan	Você administra uma organização, mas nenhuma está no Enterprise.
422	csv_head tem mais de 16.384 caracteres, não tem cabeçalho, duplica uma coluna ou não possui linha completa. O campo detail explica.
429, limite de taxa	Mais de 30 propostas por conta na última hora.
429, créditos de IA	Créditos de IA da organização esgotados.
502 mapping proposal unavailable	Proposta indisponível. Tente de novo ou escreva manualmente.

Como distinguir os dois erros 429

Ambas as recusas retornam 429. Leia o corpo:

	Limite de taxa	Créditos de IA esgotados
Corpo	{ "detail": "at most 30 mapping proposals per hour" }	Corpo padrão de cota
Reconhecimento	Não há error; detail contém a frase acima.	"error": "quota_exceeded", com limit, used, remaining, reset_at.
Ação	Espere; o limite considera a última hora por conta.	Aguarde reset_at, adicione créditos ou mapeie manualmente.

{
  "error": "quota_exceeded",
  "detail": "Usage limit reached. Please try again later.",
  "tier": "enterprise",
  "remaining": 0,
  "reset_at": "2026-11-01T04:00:00+00:00",
  "period": "month",
  "reset_in_seconds": 1296000
}

O exemplo omite quatro campos que estão presentes. limit e used representam a cota contratual da organização e o consumo. product e meter apontam para o contador do Studio, não da API, pois a proposta é um recurso do Studio. O conjunto de créditos é o mesmo. Diferencie pelo campo error, como em qualquer recusa por cota.

Como uma proposta é cobrada:

• Requisições recusadas com 403, 422 ou 429 por taxa não gastam créditos. Uma solicitação rejeitada com 422 por causa da amostra também conta no limite de 30 por hora.
• Uma proposta que não recebeu resposta (502) não gasta créditos.
• Uma resposta gerada, mas inutilizável (também 502), é cobrada pelos tokens da resposta.
• Uma proposta entregue com errors não vazio foi gerada e é cobrada normalmente.

No Studio, as mensagens diferenciam o limite de propostas por hora do esgotamento de créditos de IA. Você ainda pode editar ou escrever o mapeamento manualmente, sem gastar créditos.

2. Prepare uma prévia

Requisição	POST /shared-api/datahub/ingests
Quem	Proprietário ou administrador, Enterprise
Cabeçalho	Idempotency-Key, obrigatório, de 8 a 128 caracteres

Campo do corpo	Tipo	Padrão	Significado
filename	string, até 200 caracteres	Obrigatório	Deve terminar em .csv ou .json; a extensão escolhe o leitor.
artifact	string	Obrigatório	Texto bruto do arquivo.
source	"csv", "api" ou "manual"	"csv"	Rótulo da origem, não escolhe o parser. "json" é inválido e retorna 422.
mapping_spec	object, até 64 KB	Nenhum	Mapeamento de colunas para CSV; omita para CSV simples ou pacote JSON.
preview	boolean	false	true prepara dados para inspeção sem publicar; false publica após leitura.
org_id	UUID	Organização principal	Organização para a qual envia.

curl -X POST https://api.kaleidr.com/shared-api/datahub/ingests \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: places-2026-10-10-a" \
  -d '{
    "filename": "places.csv",
    "source": "csv",
    "preview": true,
    "artifact": "name,timezone,lat,lng,address,category\nHarbor Hotel,Europe/London,51.5079,-0.0877,\"1 Example Street, London\",hotel\n"
  }'

{
  "ingest_id": "5f0c2a1e-…",
  "release_id": "a81d77b0-…",
  "status": "pending",
  "status_url": "/shared-api/datahub/ingests/5f0c2a1e-…",
  "dispatched": true
}

Idempotency-Key vale por organização. Repetir uma chave retorna a ingestão já criada com dispatched: false, sem criar outra. Use uma nova chave para preparar novamente após editar o mapeamento; a antiga retornaria o resultado anterior.

dispatched indica se a chamada iniciou o processamento. Em nova ingestão, false significa que ficou pending. Inicie-a com a chamada de reenvio.

Use preview: true no primeiro envio e sempre que o mapeamento mudar.

Uma ingestão por vez e um limite por hora. Um novo envio é recusado se outra ingestão da organização estiver processando ou se 30 envios foram iniciados na última hora:

Status	detail	Significado	Ação
409	org_ingest_in_progress	Outra ingestão está running.	Consulte o estado até succeeded ou failed e repita com o mesmo Idempotency-Key.
429	ingest_rate_limited	A organização criou 30 ingestões na última hora, incluindo prévias.	Aguarde; valide o mapeamento com proposta em vez de preparar repetidamente.
413	request_body_too_large	Requisição completa excede 32 MiB.	Reduza o arquivo. Veja Limites.

Reenviar um Idempotency-Key já utilizado não cria outro upload: retorna a ingestão existente e não é recusado com os códigos 409 ou 429 acima. O corpo não é comparado com o original; um arquivo diferente enviado com uma chave já usada é descartado. No entanto, a solicitação é verificada antes da consulta à chave e uma repetição pode ser recusada com 413, com 403 org_admin_required ou vendor_data_not_on_plan, ou com 422 por qualquer um dos limites. A chave é lembrada enquanto a versão correspondente existir. Depois que ela for excluída ou removida automaticamente, a mesma chave iniciará um novo upload.

3. Verifique o resultado

Requisição	GET /shared-api/datahub/ingests/{ingest_id}
Quem	Proprietário ou administrador, qualquer plano

curl https://api.kaleidr.com/shared-api/datahub/ingests/5f0c2a1e-… \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

{
  "ingest_id": "5f0c2a1e-…",
  "release_id": "a81d77b0-…",
  "status": "succeeded",
  "attempts": 1,
  "row_counts": {
    "places": 1,
    "room_types": 0,
    "rate_plans": 0,
    "daily_rates": 0,
    "daily_inventory": 0,
    "hours": 0,
    "documents": 0
  },
  "error_report": null,
  "created_at": "2026-10-10T09:12:04Z",
  "started_at": "2026-10-10T09:12:20Z",
  "finished_at": "2026-10-10T09:12:41Z"
}

O status muda de pending para running e finalmente succeeded ou failed.

• Com succeeded, row_counts informa os itens reconhecidos por tipo. Compare com a contagem esperada antes de publicar.
• Com failed, error_report.errors descreve problemas por linha, até 200 entradas; error_report.error_count informa o total. Uma falha não altera a versão publicada.

{
  "status": "failed",
  "error_report": {
    "errors": [
      "places[1]: missing lat/lng -- supply coordinates, or an address to geocode from",
      "places[2]: unknown timezone 'London'"
    ],
    "error_count": 2
  }
}

Um envio é tudo ou nada: se alguma linha falha na validação, nada é preparado. Corrija o arquivo e envie novamente com um novo Idempotency-Key.

4. Publique

Requisição	POST /shared-api/datahub/ingests/{ingest_id}/publish
Quem	Proprietário ou administrador, Enterprise
Corpo	Nenhum

curl -X POST https://api.kaleidr.com/shared-api/datahub/ingests/5f0c2a1e-…/publish \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

A resposta tem o formato da preparação, com status: "pending". A publicação só é possível quando a ingestão foi criada com preview: true e terminou em succeeded.

A publicação processa o arquivo novamente. Lê o mesmo arquivo e mapeamento, por isso contagens e identificadores permanecem. Um local fornecido apenas por endereço é geocodificado novamente e as coordenadas podem mudar ligeiramente.

Consulte o status novamente. A ingestão volta a pending, executa e termina em succeeded; nesse momento a versão é publicada e a anterior é substituída.

Trate o 409 aqui como “já em andamento”, não como sinal para tentar novamente. Essa chamada não exige Idempotency-Key. Se a primeira tentativa tiver funcionado mas perdido a resposta, a repetição retorna 409 ingest_is_not_a_preview, ou 409 publish_already_in_progress quando se sobrepõe. Consulte o status da ingestão.

Um código 409 é diferente: org_ingest_in_progress significa que outro upload da organização está sendo processado, portanto esta publicação não foi iniciada. Aguarde a outra ingestão atingir succeeded ou failed e solicite a publicação novamente.

Publicação em uma etapa

Envie preview: false ou omita preview para publicar logo após ler o arquivo, sem chamada separada. Ideal para envios recorrentes com mapeamento já conferido.

Reiniciar ingestão parada

Requisição	POST /shared-api/datahub/ingests/{ingest_id}/dispatch
Quem	Proprietário ou administrador, Enterprise

Use quando uma ingestão permanece pending (por exemplo, dispatched: false) ou falhou por causa externa aos dados. Cada ingestão pode ser processada no máximo três vezes. (dispatched; false; failed)

Status	Significado
409 ingest_already_succeeded	Concluída, nenhuma ação necessária.
409 ingest_already_running	Já está processando.
409 ingest_attempts_exhausted	Três tentativas usadas; faça novo upload com outro Idempotency-Key.
409 org_ingest_in_progress	Outra ingestão está em processamento; aguarde e tente depois.
404 ingest_not_found	Não há ingestão com esse identificador na organização, ou a versão está sendo excluída ou já foi excluída. Não há nada para reiniciar.

Listar versões

Requisição	GET /shared-api/datahub/releases
Quem	Proprietário ou administrador, qualquer plano
Consulta	status opcional: draft, published, superseded, failed ou deleting (outro valor retorna 422 unknown_release_status); org_id opcional

curl "https://api.kaleidr.com/shared-api/datahub/releases?status=published" \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

[
  {
    "id": "a81d77b0-…",
    "status": "published",
    "published_at": "2026-10-10T09:15:02Z",
    "superseded_at": null,
    "created_at": "2026-10-10T09:12:04Z",
    "state": "published",
    "ingest_id": "5f0c2a1e-…"
  }
]

Campo	Tipo	Significado
id	UUID	ID da versão usado para despublicar e excluir.
status	string	draft, published, superseded, failed ou deleting.
published_at	timestamp ou null	Quando foi publicada.
superseded_at	timestamp ou null	Quando deixou de ser atual.
created_at	timestamp	Quando o envio foi aceito.
state	string	Ações disponíveis atualmente, conforme tabela seguinte.
ingest_id	UUID ou null	Ingestão da versão, usada para status e publicação.

state diferencia duas situações dentro de status: draft, permitindo oferecer a ação certa sem outra consulta: (status)

state	status	Significado	Ação possível
processing	draft	Envio na fila ou processamento, inclusive publicação direta e publicação de prévia.	Aguarde; é possível excluí-lo.
preview	draft	Prévia concluída aguardando decisão.	Publicar ou excluir.
published	published	Versão usada nas respostas.	Despublicar.
superseded	superseded	Substituída, despublicada ou prévia expirada.	Excluir.
failed	failed	Envio não pôde ser lido.	Excluir.
deleting	deleting	Exclusão em andamento.	Nenhuma.

A lista inclui as 50 versões mais recentes, da mais nova à mais antiga. Pode haver no máximo uma published por organização, ou nenhuma após despublicar. Versões em deleting só aparecem com ?status=deleting e desaparecem de todas as listas após concluir.

Retirar uma versão

Duas chamadas removem dados por motivos distintos: unpublish retira a versão publicada de uso; delete apaga uma versão não publicada. Ambas são permitidas a proprietários ou administradores de qualquer plano, inclusive após downgrade. Não levam corpo nem Idempotency-Key e podem ser repetidas com segurança.

Pelo Kaleidr Studio

Cada linha em Releases, na seção Data for AI Answers, oferece a ação apropriada e pede confirmação. Proprietários e administradores que saíram do Enterprise continuam vendo a lista e as ações enquanto possuírem versões, com a mensagem “Uploading is part of the Enterprise plan.”

Rótulo	Ação	Confirmação	Depois
Published	Unpublish	“Unpublish this release? Kaleidr AI stops answering from this data until you publish another release. This release cannot be published again.”	“Unpublishing…”, depois “Unpublished. Kaleidr AI no longer answers from this data.”; estado vira Superseded.
Draft, Superseded, Failed	Delete	“Delete this release? This removes the release and everything made from it, and cannot be undone.”	“Deleting…”, depois “Release deleted.”; linha some.
Processing	Nenhuma

Cada confirmação oferece o botão da ação e Cancel. A interface não apresenta Delete para uma versão publicada. Se tentada pela API, exibe “This release is published. Unpublish it before you delete it.” Veja Lista de versões.

Despublicar uma versão

Requisição	POST /shared-api/datahub/releases/{release_id}/unpublish
Quem	Proprietário ou administrador, qualquer plano
Corpo	Nenhum
Consulta	org_id, opcional

curl -X POST https://api.kaleidr.com/shared-api/datahub/releases/a81d77b0-…/unpublish \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

{ "release_id": "a81d77b0-…", "status": "superseded" }

A versão deixa de ser usada assim que a chamada retorna. Consequências:

• A organização fica sem versão publicada até publicar outra. A versão anterior não volta automaticamente. As respostas continuam com conhecimento geral e não avisam que os dados saíram.
• Essa versão não pode ser republicada. Envie e publique novamente o arquivo para restaurar os dados.
• A versão permanece como superseded na lista e pode ser excluída, ou será removida automaticamente.

Status	detail	Significado
200		A versão está superseded. Repetições retornam 200, inclusive quando outra versão já a substituiu. superseded
403	org_admin_required	Usuário não é proprietário nem administrador.
404	release_not_found	ID não encontrado ou exclusão em andamento.
409	release_not_published	Versão ainda rascunho ou falha; nunca esteve publicada.

Excluir uma versão

Requisição	DELETE /shared-api/datahub/releases/{release_id}
Quem	Proprietário ou administrador, qualquer plano
Corpo	Nenhum
Consulta	org_id, opcional

curl -X DELETE https://api.kaleidr.com/shared-api/datahub/releases/a81d77b0-… \
  -H "Authorization: Bearer $KALEIDR_ACCESS_TOKEN"

HTTP/1.1 202 Accepted

{ "release_id": "a81d77b0-…", "status": "deleting", "dispatched": true }

Excluir remove a versão, o arquivo original e tudo que a Kaleidr derivou dela. Não pode ser desfeito.

• Uma versão publicada precisa ser despublicada primeiro. Excluí-la retorna 409 release_is_published. Qualquer outra versão pode ser excluída: prévia, substituída, falha ou ainda sendo processada.
• A resposta é 202, e a exclusão termina pouco depois. Desde a resposta, o status fica deleting, a versão sai da lista comum e não pode ser publicada; sua ingestão passa a retornar 404 ingest_not_found. Isso também se aplica à consulta de status e à nova tentativa de processamento.
• dispatched indica se a remoção começou na própria chamada. Se false, começa automaticamente depois, ou você pode repetir a chamada.
• Repetir é seguro. Enquanto apaga, retorna 202; após concluir, retorna 404 release_not_found. Considere esse 404 como “já excluída”.

Status	detail	Significado
202		A versão está deleting; repetições retornam 202 até terminar.
403	org_admin_required	Usuário não administra a organização.
404	release_not_found	Versão não existe, inclusive após exclusão concluída.
409	release_is_published	Precisa despublicar antes de excluir.

Para confirmar, consulte as versões com ?status=deleting: lista vazia significa que não resta exclusão em curso.

Remoção automática de versões antigas

Você não precisa excluir manualmente versões que deixaram de ser atuais. A Kaleidr aplica o mesmo processo de exclusão:

Versão	Quando é removida
superseded: substituída ou despublicada	30 dias após substituição/despublicação.
Prévia nunca publicada	Expira após 14 dias e é removida 30 dias depois.
failed	30 dias após a última tentativa de processamento.
published	Nunca enquanto permanecer publicada.

O que a exclusão não alcança

Uma versão excluída não é utilizada em respostas após concluir a exclusão. Isso não remove respostas em cache por tempo limitado, históricos de conversa salvos, backups ou conteúdo já enviado ao provedor do modelo durante o processamento. Veja Limitações da exclusão.

Limites

Limites definidos em contrato

O tamanho e a contagem permitidos por upload são estabelecidos no contrato da organização. A plataforma impõe um teto técnico para cada limite, que não pode ser ultrapassado pelo contrato.

Limite	Enterprise	Quando excedido
Tamanho de artifact	Definido no contrato	422 no upload
Linhas CSV, sem cabeçalho	Definido no contrato	422 no upload
Locais em pacote JSON	Definido no contrato	422 no upload
Documentos em pacote JSON	Definido no contrato	422 no upload

• GET /shared-api/datahub/limits retorna os limites da organização.
• Free e Pro não têm limites de upload porque não podem enviar. Retornam 403 vendor_data_not_on_plan.
• Os limites são por organização. A publicação substitui a versão inteira, então cada limite controla um upload e os dados publicados.

Um envio que ultrapassa esses limites retorna 422, e a razão identifica o limite e o plano. <count> representa a quantidade enviada e <limit> o valor contratado:

{ "detail": { "errors": ["<count> places exceed the limit of <limit> (enterprise plan)"] } }

As demais razões usam formatos como <count> documents exceed the limit of <limit> (enterprise plan), csv has more than <limit> rows; the places limit is <limit> (enterprise plan) e artifact is <size> MB; the limit is <limit> MB (enterprise plan). Se o arquivo excede o tamanho máximo, ele não é processado e essa é a única razão apresentada.

Limites gerais

Limite	Valor	Quando excedido
Requisição inteira de upload	32 MiB	413 request_body_too_large
Tipos de quarto por upload	10.000	422 em JSON; ingestão falha em planilha mapeada
Planos tarifários por upload	10.000	422 em JSON; ingestão falha em planilha mapeada
Linhas de horário em JSON	25.000	422 no envio
Linhas de tarifas por noite e disponibilidade, juntas por upload	200.000	Falha na ingestão: daily facts: <count> rows exceed the cap of 200000
Texto de todos os documentos juntos por upload	No máximo cerca de 600.000 caracteres, menos quando distribuídos em muitos documentos	Falha na ingestão: documents: chunk count exceeds the cap of 500
Profundidade do JSON	Estruturas muito aninhadas são recusadas	422 no envio
mapping_spec	64 KB	422 no envio
filename	200 caracteres, extensão .csv ou .json	422 no envio
Ingestões simultâneas por organização	1	409 org_ingest_in_progress (no upload, na publicação e no reenvio para processamento)
Novos envios por organização	30 por hora	429 ingest_rate_limited
csv_head para proposta	16.384 caracteres	422
Propostas	30 por conta por hora; gastam créditos de IA	429; veja Distinguir erros 429
Tentativas de ingestão	3	409 ao redisparar
Prévia nunca publicada	14 dias	409 ao publicar
Versão não atual	30 dias	Removida automaticamente

O limite da requisição é maior que o do arquivo porque o conteúdo é uma string JSON e os escapes aumentam seu tamanho. Acima de 32 MiB a requisição é recusada com 413 sem leitura. Arquivo acima do limite contratual, mas dentro da requisição, recebe 422.

Tamanho ou contagem acima do limite retorna 422 com até 200 razões listadas. Por exemplo, quando o total de linhas supera um limite comum a todas as organizações:

{ "detail": { "errors": ["10001 room_types exceed the cap of 10000"] } }

Um JSON aninhado demais retorna uma resposta da mesma forma:

{ "detail": { "errors": ["upload is nested too deeply"] } }

O limite CSV conta linhas independentemente do conteúdo. Uma planilha com uma linha por diária atinge rapidamente esse teto. Para grandes volumes de tarifas e disponibilidade, use pacote JSON; locais, documentos, tipos de quarto, planos e horários são contados no envio.

Limites por campo

Cada valor tem tamanho máximo. Texto é medido em caracteres. Valores JSON livres, como objetos e arrays, são medidos em bytes após serialização.

Lista	Campo	Limite
Todas	ref, place_ref, room_type_ref, rate_plan_ref	128 caracteres
places	name	200 caracteres
places	category	100 caracteres
places	timezone	64 caracteres
places	overture_id (opcional)	128 caracteres
places	address	2.048 bytes como JSON
places	schema_org (objeto opcional)	16.384 bytes como JSON
room_types	name	200 caracteres
room_types	amenities (array opcional), attributes (objeto opcional)	8.192 bytes cada, como JSON
rate_plans	name	200 caracteres
rate_plans	currency (opcional)	3 caracteres
rate_plans	cancellation_policy (opcional)	2.000 caracteres
rate_plans	board_basis (opcional)	100 caracteres
rate_plans	attributes (objeto opcional)	8.192 bytes como JSON
hours	note (opcional)	500 caracteres
documents	title	300 caracteres

O momento da validação depende do formato enviado:

• Pacote JSON: validado durante a requisição; retorna 422 com razões por linha e campo, como places[3]: name is longer than 200 characters ou room_types[0]: amenities is larger than 8192 bytes as JSON.
• CSV de locais ou planilha mapeada: validado durante o processamento; a ingestão termina em failed e as razões aparecem em error_report.errors.

Um JSON livre com NaN ou Infinity gera a razão <list>[<row>]: <field> holds a non-finite number.

Expiração de prévias

Uma prévia não publicada expira 14 dias após a preparação. Ela vira superseded e aparece temporariamente na lista, mas não pode mais ser publicada. A tentativa retorna 409 no_previewed_release_to_publish. Faça novo upload. A versão é removida automaticamente 30 dias após expirar; você pode excluí-la antes.

Observações sobre campos

timezone é obrigatório para todos os locais e altera as respostas. Tarifas e disponibilidade usam o calendário do local: “esta noite” em Sydney não é necessariamente o mesmo dia que em Londres. Se não houver coluna de fuso, mapeie uma constante:

{ "timezone": { "const": "Australia/Sydney" } }

Escolha o fuso com cuidado. Um fuso incorreto produz respostas aparentemente certas durante o dia e erradas perto da meia-noite. Fusos ausentes ou nomes IANA inválidos causam erro.

Envie coordenadas quando possível. lat e lng são usados exatamente como fornecidos. Locais apenas com endereço são geocodificados; se a correspondência não for suficientemente confiável, a linha falha e você precisa fornecer coordenadas. Um local no ponto errado é pior que um endereço não resolvido.

Reenviar o mesmo arquivo é seguro. Na planilha mapeada, identificadores vêm das colunas em ref_from. A mesma exportação gera os mesmos IDs. Uma nova versão substitui a anterior, sem acrescentar linhas a ela.

Cada versão é completa e independente. Nada passa da versão anterior. Se o novo arquivo omite os locais do mês passado, eles deixam de aparecer nas respostas após a publicação.

Envie texto em UTF-8. Arquivos ZIP, compactados com gzip ou PDFs renomeados como .csv ou .json são recusados.

Erros

Erros das chamadas de upload usam { "detail": "<code>" }, exceto quando retornam uma lista de razões.

Status	detail	Significado
401		Token ausente, expirado ou não é access token.
403	org_admin_required	Conta sem função de proprietário ou administrador.
403	vendor_data_not_on_plan	Organização fora do Enterprise; chamadas de leitura, despublicação e exclusão não sofrem essa restrição.
404	ingest_not_found	Ingestão inexistente ou versão apagando/apagada.
404	release_not_found	Versão não encontrada na organização.
409	release_not_published	Despublicar versão rascunho ou falha.
409	release_is_published	Tentativa de excluir versão publicada; despublique primeiro.
409	ingest_conflict	Duas requisições com mesmo Idempotency-Key colidiram; tente novamente.
409	ingest_is_not_a_preview	Não era prévia ou publicação já solicitada.
409	ingest_already_running	Processamento em andamento.
409	no_previewed_release_to_publish	Prévia falhou, está processando ou expirou.
409	publish_already_in_progress	Publicações simultâneas; uma já está sendo executada.
409	ingest_already_succeeded	Tentativa de processar novamente uma ingestão concluída.
409	ingest_attempts_exhausted	Três tentativas já utilizadas.
409	org_ingest_in_progress	Outra ingestão da organização em andamento.
413	request_body_too_large	Upload superior a 32 MiB; outras chamadas limitadas a 1 MiB.
422	{ "errors": [ … ] }	Limites, campo muito grande, JSON profundo ou CSV/JSON inválido; até 200 razões. Referência Referência
429	ingest_rate_limited	30 uploads da organização na última hora.
422	Lista de validação	Ausência de Idempotency-Key, extensão inválida ou source fora dos valores permitidos.
422	unknown_release_status	Filtro status não é um dos cinco valores permitidos.

Um arquivo acima do limite contratual retorna 422 e apresenta a razão em errors. O 413 indica que a requisição inteira excedeu o limite, com corpo { "detail": "request_body_too_large" }.

A proposta de mapeamento tem seus próprios erros, listados em Propor mapeamento. Retorna 403 org_admin_required ou vendor_data_not_on_plan para quem não pode enviar, e 429 quando se esgotam propostas por hora ou créditos de IA.

Ainda não disponível

• Atualizações incrementais. Não há upsert, remoção individual nem consulta de “alterações desde”; uma versão substitui completamente a outra e pode ser despublicada ou excluída.
• Republicar uma versão antiga. Uma versão substituída ou despublicada não pode ser restaurada diretamente. Envie o arquivo novamente.
• Mapeamentos armazenados. O mapeamento precisa acompanhar cada envio; não pode ser salvo para uso por ID.
• Conectores. A Kaleidr não busca dados de banco, sistema de reservas ou serviço de planilhas.
• Upload multipart ou binário. O arquivo é enviado como string dentro do corpo JSON.

Páginas relacionadas

• Respostas com seus próprios dados: processo completo, planos, limites e verificação, além do recurso separado de dados nos mapas em todos os planos.
• Autenticação e escopos: criar a chave que lê os dados.
• Erros: catálogo de erros da plataforma.