{"openapi":"3.1.0","info":{"title":"Nock API","version":"1.0.0","summary":"B2B search, enrichment, and outreach API for Nock workspaces.","description":"Nock API v1 for people and company search, cascade enrichment, web research, AI columns, outreach campaigns, and credit balance. Authenticate with a dashboard API key (`Authorization: Bearer nock_live_…`) or Clerk OAuth for MCP. Prefer the `/v1` server. The unversioned origin is an alias of v1. Backwards-compatible fields may appear without a new version. Breaking changes ship under `/v2` and the retired prefix receives `Deprecation` and `Sunset` headers with at least 90 days of notice. Rate limits are advertised on every response via IETF RateLimit headers; HTTP 429 includes Retry-After. JSON errors use `{ error, message? }`."},"servers":[{"url":"https://api.usenock.com/v1","description":"Nock API v1 (preferred)"},{"url":"https://api.usenock.com","description":"Unversioned alias of v1"}],"tags":[{"name":"Catálogo"},{"name":"Busca"},{"name":"Enriquecimento"},{"name":"IA"},{"name":"Prospecção"},{"name":"Créditos"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"nock_live_…","description":"Workspace API key. Current keys grant every documented OAuth scope. Send Authorization: Bearer <key>."},"oauth2":{"type":"oauth2","description":"Clerk OAuth used by the Nock MCP server. Request only the scopes you need.","flows":{"authorizationCode":{"authorizationUrl":"https://clerk.usenock.com/oauth/authorize","tokenUrl":"https://clerk.usenock.com/oauth/token","scopes":{"catalog:read":"Read the provider catalog and health of the Nock API.","search:write":"Search people and companies and hydrate search results.","enrich:write":"Enrich a person or company through the provider cascade.","research:write":"Run web research and AI column generation.","outreach:read":"List campaigns, templates, prospects, and events.","outreach:write":"Create and update campaigns, templates, cadences, and prospects.","credits:read":"Read the workspace credit balance and ledger."}}}}},"parameters":{"NockVersion":{"name":"Nock-Version","in":"header","required":false,"description":"Optional API version pin. v1 is the default and the only released version.","schema":{"type":"string","enum":["1"],"default":"1"}}},"schemas":{"Error":{"type":"object","required":["error"],"additionalProperties":false,"properties":{"error":{"type":"string","description":"Machine-readable code such as unauthorized or rate_limited."},"message":{"type":"string","description":"Human-readable explanation of the failure."}}}}},"security":[{"bearerAuth":[]},{"oauth2":["catalog:read","search:write","enrich:write","research:write","outreach:read","outreach:write","credits:read"]}],"paths":{"/health":{"get":{"tags":["Catálogo"],"summary":"Verificar disponibilidade","security":[],"responses":{"200":{"description":"API disponível","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"status":"ok"}}}}},"operationId":"getHealth","description":"Verificar disponibilidade","parameters":[{"$ref":"#/components/parameters/NockVersion"}]}},"/api/providers":{"get":{"tags":["Catálogo"],"summary":"Listar provedores e campos disponíveis","security":[],"responses":{"200":{"description":"Catálogo atual de provedores e enriquecimentos","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}},"operationId":"listProviders","description":"Listar provedores e campos disponíveis","parameters":[{"$ref":"#/components/parameters/NockVersion"}]}},"/api/sourcing/people":{"post":{"tags":["Busca"],"summary":"Buscar pessoas","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jobTitle":{"type":"string"},"seniorities":{"type":"array","items":{"type":"string"}},"roles":{"type":"array","items":{"type":"string"}},"companySizes":{"type":"array","items":{"type":"string"}},"company":{"type":"string"},"domain":{"type":"string"},"industry":{"type":"string"},"personIndustry":{"type":"string"},"skills":{"type":"string"},"location":{"type":"string"},"companyLocation":{"type":"string"},"revenueRange":{"type":"string"},"technologies":{"type":"array","items":{"type":"string"}},"emailStatuses":{"type":"array","items":{"type":"string","enum":["verified","likely to engage","unverified","unavailable"]}},"language":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":25},"sourceOrder":{"type":"array","items":{"type":"string"}}}},"example":{"jobTitle":"Head of Sales","location":"São Paulo","limit":10}}}},"responses":{"200":{"description":"Pessoas encontradas","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Saldo de créditos insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"searchPeople","description":"Buscar pessoas","parameters":[{"$ref":"#/components/parameters/NockVersion"}],"security":[{"bearerAuth":[]},{"oauth2":["search:write"]}]}},"/api/sourcing/people/stream":{"post":{"tags":["Busca"],"summary":"Buscar pessoas (stream)","description":"Mesmos filtros de /api/sourcing/people; envia páginas SSE conforme cada fonte adiciona linhas.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jobTitle":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":25},"sourceOrder":{"type":"array","items":{"type":"string"}}}},"example":{"jobTitle":"Head of Sales","location":"São Paulo","limit":10}}}},"responses":{"200":{"description":"text/event-stream com páginas parciais e um evento done","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Saldo de créditos insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"searchPeopleStream","parameters":[{"$ref":"#/components/parameters/NockVersion"}],"security":[{"bearerAuth":[]},{"oauth2":["search:write"]}]}},"/api/sourcing/people/hydrate":{"post":{"tags":["Busca"],"summary":"Enriquecer pessoas já buscadas","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"leads":{"type":"array","maxItems":25,"items":{"type":"object"}}},"required":["leads"]},"example":{"leads":[{"name":"Ada Lovelace","company":"Analytical Engines"}]}}}},"responses":{"200":{"description":"Pessoas enriquecidas","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Saldo de créditos insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"hydratePeople","description":"Enriquecer pessoas já buscadas","parameters":[{"$ref":"#/components/parameters/NockVersion"}],"security":[{"bearerAuth":[]},{"oauth2":["search:write"]}]}},"/api/companies/search":{"post":{"tags":["Busca"],"summary":"Buscar empresas","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"industry":{"type":"string"},"keywords":{"type":"array","items":{"type":"string"}},"sizes":{"type":"array","items":{"type":"string"}},"location":{"type":"string"},"cnaes":{"type":"array","items":{"type":"string"}},"registrationStatuses":{"type":"array","items":{"type":"string","enum":["ATIVA","BAIXADA","INAPTA","NULA","SUSPENSA"]}},"establishmentTypes":{"type":"array","items":{"type":"string","enum":["MATRIZ","FILIAL"]}},"fiscalSizes":{"type":"array","items":{"type":"string","enum":["01","02","03","05"]}},"capitalMin":{"type":"number","minimum":0},"capitalMax":{"type":"number","minimum":0},"legalNatureCodes":{"type":"array","items":{"type":"string"}},"partnerName":{"type":"string"},"partnerDocument":{"type":"string"},"simpleOption":{"type":"boolean"},"openingDateMin":{"type":"string","format":"date"},"openingDateMax":{"type":"string","format":"date"},"hasPhone":{"type":"boolean"},"hasEmail":{"type":"boolean"},"state":{"type":"string","minLength":2,"maxLength":2},"city":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":20},"companyOrder":{"type":"array","items":{"type":"string"}}}},"example":{"keywords":["autopeças"],"registrationStatuses":["ATIVA"],"legalNatureCodes":["2062"],"simpleOption":true,"openingDateMin":"2020-01-01","hasPhone":true,"state":"PR","city":"Curitiba","limit":10}}}},"responses":{"200":{"description":"Empresas encontradas","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Saldo de créditos insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"searchCompanies","description":"Buscar empresas","parameters":[{"$ref":"#/components/parameters/NockVersion"}],"security":[{"bearerAuth":[]},{"oauth2":["search:write"]}]}},"/api/companies/search/stream":{"post":{"tags":["Busca"],"summary":"Buscar empresas (stream)","description":"Mesmos filtros de /api/companies/search; envia páginas SSE conforme cada fonte adiciona linhas.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":25},"companyOrder":{"type":"array","items":{"type":"string"}}}},"example":{"keywords":["autopeças"],"state":"PR","limit":10}}}},"responses":{"200":{"description":"text/event-stream com páginas parciais e um evento done","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Saldo de créditos insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"searchCompaniesStream","parameters":[{"$ref":"#/components/parameters/NockVersion"}],"security":[{"bearerAuth":[]},{"oauth2":["search:write"]}]}},"/api/companies/cnpj/batch":{"post":{"tags":["Busca"],"summary":"Consultar empresas por CNPJ em lote","description":"Hidrata de 1 a 500 CNPJs preservando a primeira ocorrência e informa separadamente quais documentos válidos não foram encontrados. CNPJs inválidos geram erro 400 e nunca são tratados como empresa ausente.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["cnpjs"],"properties":{"cnpjs":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"string"}}}},"example":{"cnpjs":["04.447.476/0001-26","01.245.502/0001-45"]}}}},"responses":{"200":{"description":"Empresas consultadas","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"results":[{"cnpj":"04447476000126","name":"ESTAMPARIA DE METAIS EBENEZER","source":"Nock Registry"}],"notFound":["01245502000145"],"invalid":[]}}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Saldo de créditos insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"lookupCompaniesByCnpj","parameters":[{"$ref":"#/components/parameters/NockVersion"}],"security":[{"bearerAuth":[]},{"oauth2":["search:write"]}]}},"/api/enrich":{"post":{"tags":["Enriquecimento"],"summary":"Enriquecer uma pessoa ou empresa","description":"Envie ao menos um identificador. goalFields limita os campos desejados; providerOrder é opcional.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"personalEmail":{"type":"string","format":"email"},"linkedinUrl":{"type":"string","format":"uri"},"phone":{"type":"string"},"fullName":{"type":"string"},"companyName":{"type":"string"},"companyDomain":{"type":"string"},"cnpj":{"type":"string"},"goalFields":{"type":"array","items":{"type":"string"}},"providerOrder":{"type":"array","items":{"type":"string"}},"onlyListed":{"type":"boolean"}}},"example":{"fullName":"Ada Lovelace","companyDomain":"example.com","goalFields":["work_email"]}}}},"responses":{"200":{"description":"Registro enriquecido","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Saldo de créditos insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"enrichRecord","parameters":[{"$ref":"#/components/parameters/NockVersion"}],"security":[{"bearerAuth":[]},{"oauth2":["enrich:write"]}]}},"/api/research":{"post":{"tags":["IA"],"summary":"Pesquisar um registro na web","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string"},"name":{"type":"string"},"company":{"type":"string"},"companyDomain":{"type":"string"},"website":{"type":"string"},"linkedinUrl":{"type":"string"},"webSearch":{"type":"boolean"},"columns":{"type":"array","items":{"type":"object","required":["id","label","value"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"value":{"type":"string"}}}}}},"example":{"prompt":"Resuma em uma frase o que a empresa faz.","company":"Nock","companyDomain":"usenock.com","webSearch":true}}}},"responses":{"200":{"description":"Resultado determinístico da pesquisa","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Saldo de créditos insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"researchWeb","description":"Pesquisar um registro na web","parameters":[{"$ref":"#/components/parameters/NockVersion"}],"security":[{"bearerAuth":[]},{"oauth2":["research:write"]}]}},"/api/ai-column":{"post":{"tags":["IA"],"summary":"Gerar um valor de coluna com IA","description":"instruction é obrigatória. As demais propriedades string são usadas como contexto.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["instruction"],"properties":{"instruction":{"type":"string"}},"additionalProperties":{"type":"string"}},"example":{"instruction":"Classifique como Enterprise, Mid-market ou SMB.","company":"Acme","employees":"480"}}}},"responses":{"200":{"description":"Valor gerado","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"value":"Mid-market"}}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Saldo de créditos insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"generateAiColumn","parameters":[{"$ref":"#/components/parameters/NockVersion"}],"security":[{"bearerAuth":[]},{"oauth2":["research:write"]}]}},"/api/prospecting/templates":{"get":{"tags":["Prospecção"],"summary":"Listar templates de prospecção","description":"Configurações reutilizáveis de oferta, remetente, tom e contexto da empresa. Não consome créditos.","responses":{"200":{"description":"Templates do workspace","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listOutreachTemplates","parameters":[{"$ref":"#/components/parameters/NockVersion"}],"security":[{"bearerAuth":[]},{"oauth2":["outreach:read"]}]},"post":{"tags":["Prospecção"],"summary":"Criar ou atualizar um template pelo nome","description":"Salvar com um nome já existente atualiza aquele template em vez de duplicá-lo. Não consome créditos.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","offering"],"properties":{"name":{"type":"string","maxLength":120},"campaignName":{"type":"string","maxLength":120},"offering":{"type":"string","maxLength":2000},"senderName":{"type":"string","maxLength":120},"tone":{"type":"string","maxLength":200},"businessContext":{"type":"string","maxLength":20000},"language":{"type":"string","maxLength":80}}},"example":{"name":"Padrão Nock","offering":"Enriquecimento de dados B2B com cascata de provedores","senderName":"Ana","tone":"direto e consultivo","language":"Português (Brasil)"}}}},"responses":{"201":{"description":"Template salvo","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"saveOutreachTemplate","parameters":[{"$ref":"#/components/parameters/NockVersion"}],"security":[{"bearerAuth":[]},{"oauth2":["outreach:write"]}]}},"/api/prospecting/templates/{templateId}":{"patch":{"tags":["Prospecção"],"summary":"Atualizar um template","description":"Única forma de renomear um template. Campos omitidos mantêm o valor atual. Não consome créditos.","parameters":[{"$ref":"#/components/parameters/NockVersion"},{"name":"templateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id do template."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"campaignName":{"type":"string","maxLength":120},"offering":{"type":"string","maxLength":2000},"senderName":{"type":"string","maxLength":120},"tone":{"type":"string","maxLength":200},"businessContext":{"type":"string","maxLength":20000},"language":{"type":"string","maxLength":80}}},"example":{"tone":"direto e consultivo"}}}},"responses":{"200":{"description":"Template atualizado","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Template não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Já existe um template com esse nome","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateOutreachTemplate","security":[{"bearerAuth":[]},{"oauth2":["outreach:write"]}]},"delete":{"tags":["Prospecção"],"summary":"Excluir um template","parameters":[{"$ref":"#/components/parameters/NockVersion"},{"name":"templateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id do template."}],"responses":{"200":{"description":"Template excluído","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"deleted":true}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Template não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteOutreachTemplate","description":"Excluir um template","security":[{"bearerAuth":[]},{"oauth2":["outreach:write"]}]}},"/api/prospecting/campaigns":{"get":{"tags":["Prospecção"],"summary":"Listar campanhas de prospecção","description":"Cada campanha traz o total de prospecções por etapa do pipeline.","responses":{"200":{"description":"Campanhas do workspace","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listOutreachCampaigns","parameters":[{"$ref":"#/components/parameters/NockVersion"}],"security":[{"bearerAuth":[]},{"oauth2":["outreach:read"]}]},"post":{"tags":["Prospecção"],"summary":"Criar uma campanha de prospecção","description":"Cria um rascunho com nome e oferta. Opcionalmente gera uma mensagem personalizada por linha selecionada de uma planilha de pessoas, usando os rótulos das colunas como contexto. A configuração pode vir de um templateId, dos campos enviados ou de ambos (os campos enviados prevalecem). A geração de campanhas e cadências não consome créditos; busca e enriquecimento prévios seguem suas próprias regras.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","offering"],"properties":{"sheetId":{"type":"string","format":"uuid"},"rowIds":{"type":"array","maxItems":25,"items":{"type":"string"}},"templateId":{"type":"string","format":"uuid"},"name":{"type":"string","maxLength":120},"offering":{"type":"string","maxLength":2000},"senderName":{"type":"string","maxLength":120},"tone":{"type":"string","maxLength":200},"businessContext":{"type":"string","maxLength":20000},"language":{"type":"string","maxLength":80}}},"example":{"name":"Fintechs SP","offering":"Enriquecimento de dados B2B"}}}},"responses":{"201":{"description":"Prospecção criada","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"campaignId":"0f5b3b3e-8a1f-4a67-9d0d-2b6f5f0f1a11","campaignName":"Fintechs SP","created":2}}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Saldo de créditos insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Planilha ou template não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createOutreachCampaign","parameters":[{"$ref":"#/components/parameters/NockVersion"}],"security":[{"bearerAuth":[]},{"oauth2":["outreach:write"]}]}},"/api/prospecting/campaigns/{campaignId}":{"get":{"tags":["Prospecção"],"summary":"Detalhar uma campanha e suas prospecções","parameters":[{"$ref":"#/components/parameters/NockVersion"},{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id da campanha."}],"responses":{"200":{"description":"Campanha e prospecções","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Campanha não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getOutreachCampaign","description":"Detalhar uma campanha e suas prospecções","security":[{"bearerAuth":[]},{"oauth2":["outreach:read"]}]},"patch":{"tags":["Prospecção"],"summary":"Atualizar nome, oferta ou contexto de uma campanha","parameters":[{"$ref":"#/components/parameters/NockVersion"},{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id da campanha."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"offering":{"type":"string","maxLength":2000},"senderName":{"type":"string","maxLength":120},"tone":{"type":"string","maxLength":200},"businessContext":{"type":"string","maxLength":20000}}},"example":{"offering":"Enriquecimento de dados B2B para fintechs","tone":"consultative"}}}},"responses":{"200":{"description":"Campanha atualizada","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Campanha não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateOutreachCampaign","description":"Atualizar nome, oferta ou contexto de uma campanha","security":[{"bearerAuth":[]},{"oauth2":["outreach:write"]}]}},"/api/prospecting/campaigns/{campaignId}/cadence":{"patch":{"tags":["Prospecção"],"summary":"Editar a cadência da campanha ou de uma pessoa","parameters":[{"$ref":"#/components/parameters/NockVersion"},{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id da campanha."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["steps"],"properties":{"steps":{"type":"array","items":{"type":"object","properties":{"day":{"type":"integer"},"channel":{"type":"string","enum":["email","linkedin","whatsapp"]},"subject":{"type":"string"},"body":{"type":"string"}}}},"prospectId":{"type":"string","format":"uuid"}}},"example":{"steps":[{"day":1,"channel":"email","subject":"Intro","body":"Olá…"},{"day":2,"channel":"linkedin","body":"Vi o perfil…"}]}}}},"responses":{"200":{"description":"Cadência atualizada","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Etapas inválidas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Campanha não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Cadência ainda não gerada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateOutreachCadence","description":"Editar a cadência da campanha ou de uma pessoa","security":[{"bearerAuth":[]},{"oauth2":["outreach:write"]}]}},"/api/prospecting/campaigns/{campaignId}/prospects":{"post":{"tags":["Prospecção"],"summary":"Adicionar pessoas a uma campanha","description":"Gera mensagens para até 25 pessoas de uma planilha e as vincula à campanha. Linhas já presentes são ignoradas. Não consome créditos.","parameters":[{"$ref":"#/components/parameters/NockVersion"},{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id da campanha."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sheetId","rowIds"],"properties":{"sheetId":{"type":"string","format":"uuid"},"rowIds":{"type":"array","minItems":1,"maxItems":25,"items":{"type":"string"}}}},"example":{"sheetId":"0f5b3b3e-8a1f-4a67-9d0d-2b6f5f0f1a11","rowIds":["row-1","row-2"]}}}},"responses":{"201":{"description":"Pessoas adicionadas","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"ok":true,"added":2,"skipped":0}}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Saldo de créditos insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Campanha ou planilha não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Campanha já cheia","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"addCampaignProspects","security":[{"bearerAuth":[]},{"oauth2":["outreach:write"]}]}},"/api/prospecting/prospects":{"get":{"tags":["Prospecção"],"summary":"Listar prospecções","parameters":[{"$ref":"#/components/parameters/NockVersion"},{"name":"campaignId","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Filtra por campanha."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["ready","sending","awaiting_reply","replied","paused","failed"]},"description":"Filtra por etapa do pipeline."}],"responses":{"200":{"description":"Prospecções do workspace","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listProspects","description":"Listar prospecções","security":[{"bearerAuth":[]},{"oauth2":["outreach:read"]}]}},"/api/prospecting/prospects/{prospectId}":{"get":{"tags":["Prospecção"],"summary":"Detalhar uma prospecção","parameters":[{"$ref":"#/components/parameters/NockVersion"},{"name":"prospectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id da prospecção."}],"responses":{"200":{"description":"Prospecção com mensagem completa e contexto","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Prospecção não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getProspect","description":"Detalhar uma prospecção","security":[{"bearerAuth":[]},{"oauth2":["outreach:read"]}]},"patch":{"tags":["Prospecção"],"summary":"Atualizar etapa ou mensagem de uma prospecção","description":"Editar a mensagem não regenera nada e não consome créditos.","parameters":[{"$ref":"#/components/parameters/NockVersion"},{"name":"prospectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id da prospecção."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ready","sending","awaiting_reply","replied","paused","failed"]},"connectionNote":{"type":"string","maxLength":300},"emailSubject":{"type":"string","maxLength":300},"emailBody":{"type":"string","maxLength":5000}}},"example":{"status":"awaiting_reply"}}}},"responses":{"200":{"description":"Prospecção atualizada","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Prospecção não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de requisições excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateProspect","security":[{"bearerAuth":[]},{"oauth2":["outreach:write"]}]},"delete":{"tags":["Prospecção"],"summary":"Excluir uma prospecção","description":"Remove a pessoa, a mensagem e o histórico. A campanha permanece mesmo se ficar sem pessoas.","parameters":[{"$ref":"#/components/parameters/NockVersion"},{"name":"prospectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id da prospecção."}],"responses":{"200":{"description":"Prospecção excluída","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"deleted":true,"campaignDeleted":false}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Prospecção não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteProspect","security":[{"bearerAuth":[]},{"oauth2":["outreach:write"]}]}},"/api/prospecting/prospects/{prospectId}/events":{"get":{"tags":["Prospecção"],"summary":"Histórico de uma prospecção","parameters":[{"$ref":"#/components/parameters/NockVersion"},{"name":"prospectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Id da prospecção."}],"responses":{"200":{"description":"Eventos em ordem cronológica","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Prospecção não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listProspectEvents","description":"Histórico de uma prospecção","security":[{"bearerAuth":[]},{"oauth2":["outreach:read"]}]}},"/api/credits":{"get":{"tags":["Créditos"],"summary":"Consultar saldo e consumo","responses":{"200":{"description":"Saldo, totais e movimentos recentes","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Chave ausente, inválida ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getCredits","description":"Consultar saldo e consumo","parameters":[{"$ref":"#/components/parameters/NockVersion"}],"security":[{"bearerAuth":[]},{"oauth2":["credits:read"]}]}}}}