{"openapi":"3.1.0","info":{"title":"Hey Otlet API","version":"1.0.0","description":"API para integrar outros sistemas à base de conhecimento da sua empresa: fazer perguntas com respostas citadas, enviar e organizar documentos e consultar conversas."},"servers":[{"url":"https://app.heyotlet.com/api/v1"}],"security":[{"apiKey":[]}],"tags":[{"name":"chat","x-displayName":"Perguntas","description":"Pergunte à base de conhecimento e receba respostas com fontes."},{"name":"conversations","x-displayName":"Conversas","description":"Histórico das conversas criadas pela chave."},{"name":"collections","x-displayName":"Coleções","description":"Agrupamentos de documentos por assunto."},{"name":"documents","x-displayName":"Documentos","description":"Envio, consulta e remoção de documentos."},{"name":"metadata","x-displayName":"Metadados","description":"Campos de metadados definidos pela empresa."},{"name":"memories","x-displayName":"Memórias","description":"Orientações que o assistente consulta nas respostas."}],"paths":{"/company/chat":{"post":{"tags":["chat"],"operationId":"ask","summary":"Fazer uma pergunta","description":"Envia uma pergunta e recebe a resposta com as fontes citadas. Com `stream: false`, a resposta completa volta em JSON. Sem ele, a resposta chega aos poucos via Server-Sent Events, no formato de stream de mensagens do AI SDK. Para continuar uma conversa, envie o `conversationId` recebido.","x-scope":"ask.use","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AskRequest"},"example":{"message":"Qual o prazo de reembolso?","stream":false}}}},"responses":{"200":{"description":"Resposta gerada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Answer"}}},"example":{"data":{"conversationId":"6d1f0c4e-6c1b-4a8e-9f3e-2f4a1b2c3d4e","messageId":"a3b1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d","answer":"O prazo de reembolso de compras no site é de 7 dias corridos [1].","sources":[{"ref":1,"kind":"document","documentId":"f0e1d2c3-b4a5-4968-8776-5a4b3c2d1e0f","documentName":"politica-reembolso.pdf","collectionName":"Políticas","location":"p. 2","snippet":"Compras feitas no site podem ser reembolsadas em até 7 dias…","score":0.61}],"status":"complete","error":null}}},"text/event-stream":{"schema":{"type":"string","description":"Eventos `data: {...}` até `data: [DONE]`."}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A chave não tem a permissão necessária.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso não encontrado ou fora do alcance da chave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos. Veja errors para cada campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de perguntas do mês atingido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/company/chat/quota":{"get":{"tags":["chat"],"operationId":"quota","summary":"Consultar o limite de perguntas","description":"Quantas perguntas a empresa já fez no mês e qual o limite.","x-scope":"ask.use","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Quota"}}},"example":{"data":{"used":42,"limit":1000,"resetsAt":"2026-11-01T00:00:00.000Z"}}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A chave não tem a permissão necessária.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/company/conversations":{"get":{"tags":["conversations"],"operationId":"listConversations","summary":"Listar conversas","description":"Conversas criadas por esta chave, da mais recente para a mais antiga.","x-scope":"ask.use","parameters":[{"name":"page","in":"query","description":"Página, começando em 1.","schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","description":"Itens por página (até 100).","schema":{"type":"integer","default":20,"maximum":100}},{"name":"search","in":"query","description":"Texto para filtrar.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"meta":{"$ref":"#/components/schemas/Page"}}}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A chave não tem a permissão necessária.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/company/conversations/{id}":{"get":{"tags":["conversations"],"operationId":"getConversation","summary":"Ver uma conversa","description":"Mensagens da conversa, com as fontes de cada resposta.","x-scope":"ask.use","parameters":[{"name":"id","in":"path","required":true,"description":"ID da conversa.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationDetail"}}}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A chave não tem a permissão necessária.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso não encontrado ou fora do alcance da chave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/company/collections":{"get":{"tags":["collections"],"operationId":"listCollections","summary":"Listar coleções","description":"Coleções que a chave pode ver, com a contagem de documentos.","x-scope":"collections.view","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}}}}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A chave não tem a permissão necessária.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["collections"],"operationId":"createCollection","summary":"Criar coleção","x-scope":"collections.manage","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionRequest"},"example":{"name":"Manuais","description":"Manuais de produtos"}}}},"responses":{"201":{"description":"Coleção criada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Collection"}}}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A chave não tem a permissão necessária.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos. Veja errors para cada campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/company/documents":{"get":{"tags":["documents"],"operationId":"listDocuments","summary":"Listar documentos","x-scope":"documents.view","parameters":[{"name":"page","in":"query","description":"Página, começando em 1.","schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","description":"Itens por página (até 100).","schema":{"type":"integer","default":20,"maximum":100}},{"name":"search","in":"query","description":"Texto para filtrar.","schema":{"type":"string"}},{"name":"collectionId","in":"query","description":"Filtra por coleção.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Situações separadas por vírgula.","schema":{"type":"string","example":"indexed,processing"}},{"name":"metadata","in":"query","description":"Filtros de metadados em JSON. Ex.: `[{\"field\":\"area\",\"operator\":\"eq\",\"value\":\"RH\"}]`.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"meta":{"$ref":"#/components/schemas/Page"}}}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A chave não tem a permissão necessária.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos. Veja errors para cada campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["documents"],"operationId":"uploadDocuments","summary":"Enviar documentos","description":"Envio multipart com até 20 arquivos (PDF, DOCX, MD ou TXT, até 50 MB cada). Os documentos ficam com situação `queued` e passam a `indexed` quando estiverem prontos para consulta.","x-scope":"documents.upload","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["collectionId","files"],"properties":{"collectionId":{"type":"string","format":"uuid","description":"Coleção de destino."},"files":{"type":"array","items":{"type":"string","format":"binary"}},"metadata":{"type":"string","description":"Valores de metadados em JSON, aplicados a todos os arquivos."}}}}}},"responses":{"201":{"description":"Documentos recebidos.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Document"}}}}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A chave não tem a permissão necessária.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Arquivo grande demais.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos. Veja errors para cada campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/company/documents/{id}/url":{"get":{"tags":["documents"],"operationId":"documentUrl","summary":"Link para baixar o arquivo","description":"Link temporário (10 minutos) para o arquivo original.","x-scope":"documents.view","parameters":[{"name":"id","in":"path","required":true,"description":"ID do documento.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"url":{"type":"string"}}}}}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A chave não tem a permissão necessária.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso não encontrado ou fora do alcance da chave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/company/documents/{id}/metadata":{"put":{"tags":["documents"],"operationId":"updateDocumentMetadata","summary":"Atualizar metadados de um documento","description":"Substitui todos os valores de metadados do documento.","x-scope":"documents.upload","parameters":[{"name":"id","in":"path","required":true,"description":"ID do documento.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentMetadataRequest"},"example":{"metadata":{"area":"RH","versao":3},"externalId":"DOC-0001"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Document"}}}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A chave não tem a permissão necessária.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso não encontrado ou fora do alcance da chave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos. Veja errors para cada campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/company/documents/{id}":{"delete":{"tags":["documents"],"operationId":"deleteDocument","summary":"Excluir documento","description":"Remove o arquivo e o tira das próximas respostas.","x-scope":"documents.delete","parameters":[{"name":"id","in":"path","required":true,"description":"ID do documento.","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Excluído."},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A chave não tem a permissão necessária.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso não encontrado ou fora do alcance da chave.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/company/metadata-fields":{"get":{"tags":["metadata"],"operationId":"listMetadataFields","summary":"Listar campos de metadados","x-scope":"documents.view","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MetadataField"}}}}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A chave não tem a permissão necessária.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/company/memories":{"get":{"tags":["memories"],"operationId":"listMemories","summary":"Listar memórias","x-scope":"memories.view","parameters":[{"name":"page","in":"query","description":"Página, começando em 1.","schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","description":"Itens por página (até 100).","schema":{"type":"integer","default":20,"maximum":100}},{"name":"search","in":"query","description":"Texto para filtrar.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Memory"}},"meta":{"$ref":"#/components/schemas/Page"}}}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A chave não tem a permissão necessária.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["memories"],"operationId":"createMemory","summary":"Criar memória","x-scope":"memories.manage","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryRequest"},"example":{"type":"context","content":"Atendemos apenas empresas, não pessoas físicas."}}}},"responses":{"201":{"description":"Memória criada.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Memory"}}}}}},"401":{"description":"Chave ausente, inválida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A chave não tem a permissão necessária.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos. Veja errors para cada campo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"hok_…","description":"Envie `Authorization: Bearer <sua chave>` em todas as chamadas."}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"string"}}}},"Page":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageSize":{"type":"integer"}}},"AskRequest":{"type":"object","required":["message"],"properties":{"message":{"type":"string","maxLength":4000,"description":"A pergunta."},"stream":{"type":"boolean","description":"Use `false` para receber JSON em vez de eventos."},"conversationId":{"type":"string","format":"uuid","description":"Continua uma conversa existente."},"collectionId":{"type":"string","format":"uuid","description":"Restringe a busca a uma coleção."}}},"Source":{"type":"object","properties":{"ref":{"type":"integer","description":"Número citado na resposta, como [1]."},"kind":{"type":"string","enum":["document","attachment"]},"documentId":{"type":"string"},"documentName":{"type":"string"},"collectionName":{"type":"string"},"location":{"type":["string","null"],"description":"Página ou seção."},"snippet":{"type":"string"},"score":{"type":"number","description":"Similaridade entre a busca e o trecho, de 0 a 1."}}},"Answer":{"type":"object","properties":{"conversationId":{"type":"string","format":"uuid"},"messageId":{"type":"string","format":"uuid"},"answer":{"type":"string","description":"Resposta em Markdown, com citações [n]."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"status":{"type":"string","enum":["complete","truncated","error","stopped"]},"error":{"type":["string","null"]}}},"Quota":{"type":"object","properties":{"used":{"type":"integer"},"limit":{"type":["integer","null"]},"resetsAt":{"type":"string","format":"date-time"}}},"Conversation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"collectionId":{"type":["string","null"]},"messageCount":{"type":"integer"},"lastMessageAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"Message":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"},"status":{"type":"string"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"createdAt":{"type":"string","format":"date-time"}}},"ConversationDetail":{"allOf":[{"$ref":"#/components/schemas/Conversation"},{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}}}}]},"Collection":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":["string","null"]},"stats":{"type":"object","properties":{"documents":{"type":"integer"},"indexed":{"type":"integer"},"sizeBytes":{"type":"integer"}}}}},"CollectionRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":120},"description":{"type":["string","null"],"maxLength":280}}},"Document":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"mimeType":{"type":"string"},"sizeBytes":{"type":"integer"},"status":{"type":"string","enum":["queued","processing","indexed","error"]},"errorCode":{"type":["string","null"]},"pageCount":{"type":["integer","null"]},"collectionId":{"type":"string","format":"uuid"},"externalId":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":true},"indexedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"DocumentMetadataRequest":{"type":"object","required":["metadata"],"properties":{"metadata":{"type":"object","additionalProperties":true,"description":"Valores por chave de campo."},"externalId":{"type":["string","null"]}}},"MetadataField":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","number","date","boolean","select","multi_select"]},"options":{"type":"array","items":{"type":"string"}},"required":{"type":"boolean"},"filterable":{"type":"boolean"}}},"Memory":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["context","positive","negative"]},"content":{"type":"string"},"question":{"type":["string","null"]},"collectionId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}},"MemoryRequest":{"type":"object","required":["type","content"],"properties":{"type":{"type":"string","enum":["context","positive","negative"]},"content":{"type":"string","maxLength":600},"question":{"type":["string","null"]},"collectionId":{"type":["string","null"],"format":"uuid"}}}}}}