Desenvolvedores

Documentação da API

A API do Citato entrega, em JSON, o que o Citato acompanha para a sua carteira — processos, movimentação, capa, intimações, peças, prazos e novidades — e cadastra novos acompanhamentos por CNPJ, CPF, OAB, razão social ou número CNJ.

Introdução

Todas as rotas respondem no mesmo endereço, nos dois ambientes:

https://citato.blueservice.com.br

As respostas são JSON em UTF-8. Datas vêm como AAAA-MM-DD e data com hora em ISO 8601, em UTC. Toda resposta sai com Cache-Control: no-store: dado de processo não fica guardado em cache de quem está no caminho.

Primeiros passos

Peça a chave do sandbox pelo formulário de contato, dizendo que é para integração.

Teste a autenticação listando os processos — o sandbox devolve cinco, fictícios:

curl "https://citato.blueservice.com.br/v1/processos" \
  -H "Authorization: Bearer $CITATO_CHAVE"

Integre contra o sandbox, com a referência abaixo.
Vá para a produção trocando só a chave: o endereço é o mesmo.

Clientes encontram, na área logada, a coleção pronta do Postman e o OpenAPI desta referência para baixar.

Autenticação

Toda rota de /v1 exige a chave de API no cabeçalho Authorization:

Authorization: Bearer citato_...

A chave começa com citato_ e aparece uma vez só, quando é emitida: o Citato guarda só uma impressão dela e não tem como mostrá-la de novo. Guarde-a como senha — numa variável de ambiente ou num cofre, nunca no código nem em página que roda no navegador. Se ela vazar, peça a revogação e uma chave nova.

O cliente vem da chave. A requisição não diz de qual carteira ela é, e quem tenta — com um cabeçalho como X-Tenant ou um parâmetro tenant — recebe 400. Chave errada ou revogada recebe 401; chave certa de um cliente sem a API habilitada recebe 403.

Produção e sandbox

O endereço é um só. Quem decide o ambiente é a chave.

Ambiente	Chave	O que a API devolve
Produção	a da sua carteira	os seus processos, lidos das fontes oficiais
Sandbox	a de sandbox	cinco processos fictícios, para integrar sem dado real

Os processos do sandbox têm a forma dos reais — os mesmos campos, a mesma paginação, os mesmos erros —, com o ano 2099 no número (por exemplo, 0000001-11.2099.8.26.0100) e a fonte sandbox: nenhum existe em tribunal. As duas últimas movimentações dos dois primeiros vêm marcadas como novidade, para o campo noticia_em ter valor em algum lugar.

Acompanhamentos

Um acompanhamento diz ao Citato o que vigiar: um CNPJ, um CPF, uma OAB, uma razão social ou o número CNJ de um processo. Cadastre com POST /v1/monitores.

CNPJ, CPF, OAB e razão social entram na descoberta da madrugada, que procura os processos no Tribunal de Justiça de São Paulo — e só nele. O resultado aparece em GET /v1/monitores/{id}/processos no dia seguinte.
Número CNJ entra na carteira na hora, de qualquer tribunal, e a movimentação chega no ciclo seguinte. É o caminho para processo fora de São Paulo.
Repetir o cadastro não duplica: o mesmo tipo e valor devolvem o acompanhamento que já existe, com 200; o novo vem com 201. Se a rede cair no meio da resposta, mande de novo.
Pausar é PATCH /v1/monitores/{id} com {"ativo": false}: sai da descoberta, e os processos que ele trouxe continuam na carteira.

O documento vai com ou sem pontuação, e o dígito verificador é conferido: CNPJ ou CPF com dígito errado recebe 422, em vez de virar um acompanhamento que nunca acha nada. No sandbox o cadastro funciona, mas os ciclos não passam por lá; ele já traz um acompanhamento fictício, com três processos.

Novidades

O Citato marca como novidade a movimentação que chegou desde a última leitura — é o que vira alerta por e-mail. GET /v1/novidades devolve as da carteira inteira; para consultar de tempos em tempos, guarde o instante da última consulta e mande no parâmetro desde:

curl "https://citato.blueservice.com.br/v1/novidades?desde=2026-10-01T06:00:00-03:00" \
  -H "Authorization: Bearer $CITATO_CHAVE"

Os ciclos rodam de madrugada e de manhã, em dias úteis; uma consulta por hora é mais do que suficiente.

Paginação

As listas vêm em páginas, num envelope com itens, total, limite e deslocamento. O limite vai de 1 a 200 (padrão 50); para a página seguinte, some o limite ao deslocamento. O total é a contagem exata, não uma estimativa.

import os

import requests

chave = os.environ["CITATO_CHAVE"]
deslocamento, processos = 0, []
while True:
    pagina = requests.get(
        "https://citato.blueservice.com.br/v1/processos",
        params={"limite": 200, "deslocamento": deslocamento},
        headers={"Authorization": f"Bearer {chave}"},
        timeout=30,
    ).json()
    processos += pagina["itens"]
    deslocamento += pagina["limite"]
    if deslocamento >= pagina["total"]:
        break

Limites

Cada chave faz até 120 requisições por minuto. Passou disso, a resposta é 429 com o cabeçalho Retry-After, que diz em quantos segundos tentar de novo. Respeite o Retry-After em vez de repetir na hora: o laço que insiste continua barrado.

Erros

Todo erro vem no mesmo formato:

{
  "codigo": "nao_autenticado",
  "detalhe": "chave de API inválida ou revogada"
}

Compare pelo codigo, que é estável. O detalhe é para pessoas e pode mudar de texto; campos novos podem entrar na resposta de erro sem aviso.

Status	Código	Quando
400	`requisicao_invalida`	A requisição tentou dizer de qual cliente ela é — cabeçalho como `X-Tenant` ou parâmetro `tenant`. O cliente vem só da chave.
401	`nao_autenticado`	Chave ausente, inválida ou revogada.
403	`sem_permissao`	A chave é válida, mas a API não está habilitada para este cliente — ou a operação não é permitida neste ambiente.
404	`nao_encontrado`	O recurso não está nesta carteira.
409	`conflito`	Conflito com o estado atual. Reservado; nenhuma rota o devolve hoje.
422	`entrada_invalida`	Parâmetro ou corpo fora do formato ou do intervalo. O `detalhe` diz qual.
429	`excesso_de_requisicoes`	Passou do limite de requisições por minuto desta chave. Espere os segundos do cabeçalho `Retry-After`.
503	`fonte_indisponivel`	A fonte externa não respondeu a nenhuma consulta. Só a pesquisa de jurisprudência vai a uma fonte na hora; tente de novo em instantes.

Referência

GET /v1/processos Exige chave

Lista os processos deste cliente

Os processos da carteira, do mais recente para o mais antigo (pela data em que entraram no Citato), em páginas. Filtre por tribunal (ex.: tjsp). O total é a contagem exata do filtro.

Parâmetros

Nome	Onde	Tipo	Regras	Descrição
`limite`	consulta	inteiro	1 a 200 · padrão 50	Itens por página, de 1 a 200.
`deslocamento`	consulta	inteiro	a partir de 0 · padrão 0	Quantos itens pular. Para a página seguinte, some o `limite`.
`tribunal`	consulta	texto		Só os processos deste tribunal (`tjsp`).

Exemplo

curl "https://citato.blueservice.com.br/v1/processos?limite=10" \
  -H "Authorization: Bearer $CITATO_CHAVE"

import os

import requests

resposta = requests.get(
    "https://citato.blueservice.com.br/v1/processos",
    params={'limite': 10},
    headers={"Authorization": f"Bearer {os.environ['CITATO_CHAVE']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

const resposta = await fetch(
  "https://citato.blueservice.com.br/v1/processos?limite=10",
  {
    headers: { Authorization: `Bearer ${process.env.CITATO_CHAVE}` },
  },
);
if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);
const dados = await resposta.json();

Resposta — em páginas (ver Paginação)

{
  "itens": [
    {
      "id": "3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f",
      "cnj": "0000001-11.2099.8.26.0100",
      "tribunal": "tjsp",
      "origem": "manual",
      "criado_em": "2026-10-01T12:12:44.401227Z",
      "atualizado_em": "2026-10-02T09:41:03.118540Z"
    }
  ],
  "total": 5,
  "limite": 50,
  "deslocamento": 0
}

Campo	Tipo	Descrição
`id`	uuid	Identificador do processo no Citato.
`cnj`	texto	O número do processo no formato CNJ, com pontuação.
`tribunal`	texto ou `null`	A sigla do tribunal, em minúsculas (`tjsp`).
`origem`	texto	Como o processo entrou: `descoberta` (achado automaticamente), `manual` (cadastrado), `importacao`. ⚠️ Vale ler: a descoberta automática cobre um tribunal, então `manual` não é exceção rara.
`criado_em`	data e hora (ISO 8601, UTC)	Quando o processo entrou no Citato.
`atualizado_em`	data e hora (ISO 8601, UTC)	A última alteração do registro no Citato.

Respostas possíveis

Status	Código	Quando
200	—	Sucesso.
400	`requisicao_invalida`	A requisição tentou dizer de qual cliente ela é — cabeçalho como `X-Tenant` ou parâmetro `tenant`. O cliente vem só da chave.
401	`nao_autenticado`	Chave ausente, inválida ou revogada.
403	`sem_permissao`	A chave é válida, mas a API não está habilitada para este cliente — ou a operação não é permitida neste ambiente.
422	`entrada_invalida`	Parâmetro ou corpo fora do formato ou do intervalo. O `detalhe` diz qual.
429	`excesso_de_requisicoes`	Passou do limite de requisições por minuto desta chave. Espere os segundos do cabeçalho `Retry-After`.

GET /v1/processos/{cnj} Exige chave

Um processo pelo número CNJ

O processo pelo número no formato CNJ, com pontuação (NNNNNNN-DD.AAAA.J.TR.OOOO). O 404 quer dizer que o processo não está nesta carteira — não que ele não exista no tribunal.

Parâmetros

Nome	Onde	Tipo	Regras	Descrição
`cnj` Obrigatório	caminho	texto	até 25 caracteres	O número CNJ, com pontuação.

Exemplo

curl "https://citato.blueservice.com.br/v1/processos/0000001-11.2099.8.26.0100" \
  -H "Authorization: Bearer $CITATO_CHAVE"

import os

import requests

resposta = requests.get(
    "https://citato.blueservice.com.br/v1/processos/0000001-11.2099.8.26.0100",
    headers={"Authorization": f"Bearer {os.environ['CITATO_CHAVE']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

const resposta = await fetch(
  "https://citato.blueservice.com.br/v1/processos/0000001-11.2099.8.26.0100",
  {
    headers: { Authorization: `Bearer ${process.env.CITATO_CHAVE}` },
  },
);
if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);
const dados = await resposta.json();

Resposta

{
  "id": "3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f",
  "cnj": "0000001-11.2099.8.26.0100",
  "tribunal": "tjsp",
  "origem": "manual",
  "criado_em": "2026-10-01T12:12:44.401227Z",
  "atualizado_em": "2026-10-02T09:41:03.118540Z"
}

Campo	Tipo	Descrição
`id`	uuid	Identificador do processo no Citato.
`cnj`	texto	O número do processo no formato CNJ, com pontuação.
`tribunal`	texto ou `null`	A sigla do tribunal, em minúsculas (`tjsp`).
`origem`	texto	Como o processo entrou: `descoberta` (achado automaticamente), `manual` (cadastrado), `importacao`. ⚠️ Vale ler: a descoberta automática cobre um tribunal, então `manual` não é exceção rara.
`criado_em`	data e hora (ISO 8601, UTC)	Quando o processo entrou no Citato.
`atualizado_em`	data e hora (ISO 8601, UTC)	A última alteração do registro no Citato.

Respostas possíveis

Status	Código	Quando
200	—	Sucesso.
400	`requisicao_invalida`	A requisição tentou dizer de qual cliente ela é — cabeçalho como `X-Tenant` ou parâmetro `tenant`. O cliente vem só da chave.
401	`nao_autenticado`	Chave ausente, inválida ou revogada.
403	`sem_permissao`	A chave é válida, mas a API não está habilitada para este cliente — ou a operação não é permitida neste ambiente.
404	`nao_encontrado`	O recurso não está nesta carteira.
422	`entrada_invalida`	Parâmetro ou corpo fora do formato ou do intervalo. O `detalhe` diz qual.
429	`excesso_de_requisicoes`	Passou do limite de requisições por minuto desta chave. Espere os segundos do cabeçalho `Retry-After`.

GET /v1/processos/{cnj}/movimentos Exige chave

A movimentação de um processo, da mais nova para a mais velha

Os andamentos do processo, em páginas, do mais novo para o mais velho; andamento sem data vem no fim. noticia_em diz quais o Citato marcou como novidade.

Parâmetros

Nome	Onde	Tipo	Regras	Descrição
`cnj` Obrigatório	caminho	texto	até 25 caracteres	O número CNJ, com pontuação.
`limite`	consulta	inteiro	1 a 200 · padrão 50	Itens por página, de 1 a 200.
`deslocamento`	consulta	inteiro	a partir de 0 · padrão 0	Quantos itens pular. Para a página seguinte, some o `limite`.

Exemplo

curl "https://citato.blueservice.com.br/v1/processos/0000001-11.2099.8.26.0100/movimentos?limite=10" \
  -H "Authorization: Bearer $CITATO_CHAVE"

import os

import requests

resposta = requests.get(
    "https://citato.blueservice.com.br/v1/processos/0000001-11.2099.8.26.0100/movimentos",
    params={'limite': 10},
    headers={"Authorization": f"Bearer {os.environ['CITATO_CHAVE']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

const resposta = await fetch(
  "https://citato.blueservice.com.br/v1/processos/0000001-11.2099.8.26.0100/movimentos?limite=10",
  {
    headers: { Authorization: `Bearer ${process.env.CITATO_CHAVE}` },
  },
);
if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);
const dados = await resposta.json();

Resposta — em páginas (ver Paginação)

{
  "itens": [
    {
      "id": "3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f",
      "ocorrido_em": "2099-06-11",
      "tipo": null,
      "texto": "Decisão: intime-se a parte autora para manifestação no prazo de 15 dias.",
      "fonte": "sandbox",
      "escopo": "cpopg",
      "noticia_em": "2026-10-02T09:41:03.118540Z"
    }
  ],
  "total": 5,
  "limite": 50,
  "deslocamento": 0
}

Campo	Tipo	Descrição
`id`	uuid	Identificador do movimento no Citato.
`ocorrido_em`	data (AAAA-MM-DD) ou `null`	O DIA do movimento. É data, não instante: as fontes entregam dia, e inventar hora seria inventar precisão.
`tipo`	texto ou `null`	O tipo do movimento, quando a fonte o separa do texto (a base nacional do CNJ separa; o portal do TJ-SP não, e aí vem `null`).
`texto`	texto	O andamento como a fonte o publicou.
`fonte`	texto	De onde veio: `esaj_movimentos` (portal do TJ-SP), `datajud_tjsp` (base nacional do CNJ) ou `sandbox` (fictício).
`escopo`	texto ou `null`	A trilha dentro do processo: `cpopg` e `cposg` (1º e 2º grau no TJ-SP), ou o grau na base nacional (`G1`, `G2`, `JE`).
`noticia_em`	data e hora (ISO 8601, UTC) ou `null`	Quando o acompanhamento classificou este movimento como NOVIDADE, ou `null`. ⚠️ Três estados, não dois: `null` significa não avaliado (movimento importado antes de o acompanhamento existir), e não 'não é novidade'. Quem integrar filtrando por `!= null` recebe as novidades; quem quiser o oposto precisa saber que o `null` mistura as duas coisas.

Respostas possíveis

Status	Código	Quando
200	—	Sucesso.
400	`requisicao_invalida`	A requisição tentou dizer de qual cliente ela é — cabeçalho como `X-Tenant` ou parâmetro `tenant`. O cliente vem só da chave.
401	`nao_autenticado`	Chave ausente, inválida ou revogada.
403	`sem_permissao`	A chave é válida, mas a API não está habilitada para este cliente — ou a operação não é permitida neste ambiente.
404	`nao_encontrado`	O recurso não está nesta carteira.
422	`entrada_invalida`	Parâmetro ou corpo fora do formato ou do intervalo. O `detalhe` diz qual.
429	`excesso_de_requisicoes`	Passou do limite de requisições por minuto desta chave. Espere os segundos do cabeçalho `Retry-After`.

GET /v1/processos/{cnj}/capa Exige chave

A capa de um processo: classe, vara, juiz, valor, partes e advogados

O retrato atual do processo. Rica no TJ-SP (portal eSAJ); fora dele, a base nacional do CNJ traz classe e assunto, sem partes, valor nem juiz. Antes da primeira leitura, lida_em vem nulo.

Traz também a correção monetária estimada (correcao), a mesma da aba Correção da tela: sobre o valor cravado no acompanhamento, se houver, senão sobre o valor da causa. É estimativa — sem juros, sem expurgos, sem tabela prática de tribunal.

Parâmetros

Nome	Onde	Tipo	Regras	Descrição
`cnj` Obrigatório	caminho	texto	até 25 caracteres	O número CNJ, com pontuação.
`indice`	consulta	um de: ipca, inpc, ipca_e, igpm, selic, tr		O índice da correção. Sem ele, vale o escolhido para o processo na tela, e na falta dele o IPCA.

Exemplo

curl "https://citato.blueservice.com.br/v1/processos/0000001-11.2099.8.26.0100/capa" \
  -H "Authorization: Bearer $CITATO_CHAVE"

import os

import requests

resposta = requests.get(
    "https://citato.blueservice.com.br/v1/processos/0000001-11.2099.8.26.0100/capa",
    headers={"Authorization": f"Bearer {os.environ['CITATO_CHAVE']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

const resposta = await fetch(
  "https://citato.blueservice.com.br/v1/processos/0000001-11.2099.8.26.0100/capa",
  {
    headers: { Authorization: `Bearer ${process.env.CITATO_CHAVE}` },
  },
);
if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);
const dados = await resposta.json();

Resposta

{
  "fonte": "sandbox",
  "lida_em": "2026-10-02T09:40:11.204118Z",
  "classe": "Procedimento Comum Cível",
  "assunto": "Inadimplemento",
  "area": "Cível",
  "foro": "Foro Fictício Central",
  "vara": "1ª Vara Cível",
  "juiz": "Juízo Fictício",
  "valor_acao": "R$ 12345,67",
  "distribuicao": "11/01/2099 às 09:00 - Livre",
  "situacao": "Em andamento",
  "sigiloso": false,
  "relator": null,
  "orgao_julgador": null,
  "secao": null,
  "situacao_recurso": null,
  "partes": [
    {
      "papel": "Reqte",
      "polo": "ativo",
      "nome": "Empresa Fictícia Alfa Ltda",
      "advogados": [
        "Advogada Fictícia (OAB 000001/SP)"
      ]
    }
  ],
  "correcao": {
    "indice": "ipca",
    "indice_nome": "IPCA",
    "indice_origem": "padrao",
    "base_origem": "acompanhamento",
    "base_valor": "R$ 10.000,00",
    "base_moeda": "Real (R$)",
    "base_data": "2024-03-15",
    "base_data_origem": "decisao",
    "valor_inicial": "10000.00",
    "fator": "1.091234",
    "corrigido_ate": "2026-09-01",
    "valor_corrigido": "10912.34",
    "aviso": "Estimativa de correção monetária pelo índice indicado, sem juros, sem expurgos e sem a tabela prática de tribunal. Não substitui cálculo judicial homologado."
  }
}

Campo	Tipo	Descrição
`fonte`	texto ou `null`	Quem respondeu: `esaj_capa` (portal do TJ-SP, capa completa), `datajud_capa` (base nacional do CNJ, rasa) ou `sandbox`. Nulo se ainda não foi lida.
`lida_em`	data e hora (ISO 8601, UTC) ou `null`	A última leitura da capa. Nulo se nunca foi lida.
`classe`	texto ou `null`	A classe processual.
`assunto`	texto ou `null`	O assunto principal.
`area`	texto ou `null`	A área (`Cível`, `Criminal`...).
`foro`	texto ou `null`	O foro.
`vara`	texto ou `null`	A vara.
`juiz`	texto ou `null`	O juiz, como a fonte o escreve.
`valor_acao`	texto ou `null`	O valor da causa como a fonte o exibe (`R$ 250.000,00`) — texto, porque é o que o tribunal publica, e pode estar em moeda antiga.
`distribuicao`	texto ou `null`	A distribuição como a fonte a exibe (data e forma).
`situacao`	texto ou `null`	A situação do processo na fonte.
`sigiloso`	booleano ou `null`	Segredo de justiça.
`relator`	texto ou `null`	O relator (2º grau).
`orgao_julgador`	texto ou `null`	O órgão julgador (2º grau).
`secao`	texto ou `null`	A seção (2º grau).
`situacao_recurso`	texto ou `null`	A situação do recurso (2º grau).
`partes`	lista de ParteDaCapa	As partes e seus advogados. Vazia onde a fonte não traz partes.
`correcao`	objeto ou `null`	A correção monetária estimada. Nula quando falta insumo: nem valor cravado nem valor da causa, data que não se lê, valor zero, ou índice que ainda não cobre nenhum mês depois da data de partida. Nunca chuta.
`correcao.indice`	texto	O índice usado.
`correcao.indice_nome`	texto	O nome do índice.
`correcao.indice_origem`	texto	Por que este índice: `consulta` (pedido no parâmetro `indice`), `processo` (escolhido para este processo na tela) ou `padrao` (IPCA).
`correcao.base_origem`	texto	Sobre que valor a correção incide: `acompanhamento` (o valor que alguém cravou na tela, com a data da decisão) ou `causa` (o valor da causa da capa).
`correcao.base_valor`	texto	O valor de partida como está escrito — pode estar em moeda antiga.
`correcao.base_moeda`	texto	A moeda do valor de partida.
`correcao.base_data`	data (AAAA-MM-DD)	A data do valor de partida.
`correcao.base_data_origem`	texto	De onde saiu a data: `decisao` (cravada com o valor), `distribuicao` (da capa) ou `ano_do_cnj` — 1º de julho do ano do número, quando a distribuição falta ou não bate com ele (processo migrado do papel vem redistribuído).
`correcao.valor_inicial`	texto	O valor de partida em reais, já convertido pelas reformas monetárias.
`correcao.fator`	texto	O fator acumulado do índice entre as duas datas.
`correcao.corrigido_ate`	data (AAAA-MM-DD)	A última competência do índice já publicada — a data-base da correção. Não é hoje: corrigir até um mês ainda não publicado seria inventar o índice.
`correcao.valor_corrigido`	texto	O valor estimado em `corrigido_ate`, em reais.
`correcao.aviso`	texto	O que este número é, e o que ele não é.

Respostas possíveis

Status	Código	Quando
200	—	Sucesso.
400	`requisicao_invalida`	A requisição tentou dizer de qual cliente ela é — cabeçalho como `X-Tenant` ou parâmetro `tenant`. O cliente vem só da chave.
401	`nao_autenticado`	Chave ausente, inválida ou revogada.
403	`sem_permissao`	A chave é válida, mas a API não está habilitada para este cliente — ou a operação não é permitida neste ambiente.
404	`nao_encontrado`	O recurso não está nesta carteira.
422	`entrada_invalida`	Parâmetro ou corpo fora do formato ou do intervalo. O `detalhe` diz qual.
429	`excesso_de_requisicoes`	Passou do limite de requisições por minuto desta chave. Espere os segundos do cabeçalho `Retry-After`.

GET /v1/processos/{cnj}/intimacoes Exige chave

As intimações do processo publicadas no DJEN, da mais nova para a mais velha

As comunicações do Diário de Justiça Eletrônico Nacional (DJEN/CNJ) para este processo, com o teor, os destinatários e os advogados.

Parâmetros

Nome	Onde	Tipo	Regras	Descrição
`cnj` Obrigatório	caminho	texto	até 25 caracteres	O número CNJ, com pontuação.
`limite`	consulta	inteiro	1 a 200 · padrão 50	Itens por página, de 1 a 200.
`deslocamento`	consulta	inteiro	a partir de 0 · padrão 0	Quantos itens pular. Para a página seguinte, some o `limite`.

Exemplo

curl "https://citato.blueservice.com.br/v1/processos/0000001-11.2099.8.26.0100/intimacoes?limite=10" \
  -H "Authorization: Bearer $CITATO_CHAVE"

import os

import requests

resposta = requests.get(
    "https://citato.blueservice.com.br/v1/processos/0000001-11.2099.8.26.0100/intimacoes",
    params={'limite': 10},
    headers={"Authorization": f"Bearer {os.environ['CITATO_CHAVE']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

const resposta = await fetch(
  "https://citato.blueservice.com.br/v1/processos/0000001-11.2099.8.26.0100/intimacoes?limite=10",
  {
    headers: { Authorization: `Bearer ${process.env.CITATO_CHAVE}` },
  },
);
if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);
const dados = await resposta.json();

Resposta — em páginas (ver Paginação)

{
  "itens": [
    {
      "id": "3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f",
      "djen_id": 990000001,
      "disponibilizada_em": "2099-06-12",
      "tribunal": "TJSP",
      "orgao": "1ª Vara Cível - Foro Fictício Central",
      "tipo_comunicacao": "Intimação",
      "tipo_documento": "Decisão",
      "meio": "D",
      "texto": "Intimação fictícia do sandbox. Fica a parte autora intimada para manifestação no prazo de 15 dias.",
      "link": null,
      "pdf": null,
      "partes": [
        {
          "polo": "A",
          "nome": "Empresa Fictícia Alfa Ltda"
        }
      ],
      "advogados": [
        {
          "nome": "Advogada Fictícia",
          "oab": "000001",
          "uf": "SP"
        }
      ]
    }
  ],
  "total": 5,
  "limite": 50,
  "deslocamento": 0
}

Campo	Tipo	Descrição
`id`	uuid	Identificador da intimação no Citato.
`djen_id`	inteiro	O identificador da comunicação no DJEN.
`disponibilizada_em`	data (AAAA-MM-DD) ou `null`	O dia em que o DJEN disponibilizou a comunicação.
`tribunal`	texto	A sigla do tribunal, como o DJEN a escreve.
`orgao`	texto ou `null`	O órgão que publicou.
`tipo_comunicacao`	texto ou `null`	`Intimação`, `Citação`...
`tipo_documento`	texto ou `null`	O tipo do documento publicado.
`meio`	texto ou `null`	O meio da publicação (`D` = DJEN).
`texto`	texto	O teor da publicação, em texto (sem as marcações HTML).
`link`	texto ou `null`	O link do documento no sistema do tribunal, como o DJEN o repassa. Falta em parte das intimações e às vezes não abre de fora; o PDF de sempre é o `pdf`.
`pdf`	texto ou `null`	O PDF original: a certidão da publicação no DJEN (CNJ). Existe para toda intimação.
`partes`	lista de ParteDaIntimacao	Os destinatários.
`advogados`	lista de AdvogadoDaIntimacao	Os advogados destinatários, com a OAB estruturada.

Respostas possíveis

Status	Código	Quando
200	—	Sucesso.
400	`requisicao_invalida`	A requisição tentou dizer de qual cliente ela é — cabeçalho como `X-Tenant` ou parâmetro `tenant`. O cliente vem só da chave.
401	`nao_autenticado`	Chave ausente, inválida ou revogada.
403	`sem_permissao`	A chave é válida, mas a API não está habilitada para este cliente — ou a operação não é permitida neste ambiente.
404	`nao_encontrado`	O recurso não está nesta carteira.
422	`entrada_invalida`	Parâmetro ou corpo fora do formato ou do intervalo. O `detalhe` diz qual.
429	`excesso_de_requisicoes`	Passou do limite de requisições por minuto desta chave. Espere os segundos do cabeçalho `Retry-After`.

GET /v1/processos/{cnj}/pecas Exige chave

As peças públicas do processo, da mais nova para a mais velha

A lista de peças públicas (sentença, decisão, petição...) com o endereço de cada uma no portal do tribunal. Só no TJ-SP: a base nacional do CNJ não expõe peças.

Parâmetros

Nome	Onde	Tipo	Regras	Descrição
`cnj` Obrigatório	caminho	texto	até 25 caracteres	O número CNJ, com pontuação.
`limite`	consulta	inteiro	1 a 200 · padrão 50	Itens por página, de 1 a 200.
`deslocamento`	consulta	inteiro	a partir de 0 · padrão 0	Quantos itens pular. Para a página seguinte, some o `limite`.

Exemplo

curl "https://citato.blueservice.com.br/v1/processos/0000001-11.2099.8.26.0100/pecas?limite=10" \
  -H "Authorization: Bearer $CITATO_CHAVE"

import os

import requests

resposta = requests.get(
    "https://citato.blueservice.com.br/v1/processos/0000001-11.2099.8.26.0100/pecas",
    params={'limite': 10},
    headers={"Authorization": f"Bearer {os.environ['CITATO_CHAVE']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

const resposta = await fetch(
  "https://citato.blueservice.com.br/v1/processos/0000001-11.2099.8.26.0100/pecas?limite=10",
  {
    headers: { Authorization: `Bearer ${process.env.CITATO_CHAVE}` },
  },
);
if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);
const dados = await resposta.json();

Resposta — em páginas (ver Paginação)

{
  "itens": [
    {
      "id": "3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f",
      "rotulo": "Decisão",
      "data": "2099-06-11",
      "url": null
    }
  ],
  "total": 5,
  "limite": 50,
  "deslocamento": 0
}

Campo	Tipo	Descrição
`id`	uuid	Identificador da peça no Citato.
`rotulo`	texto ou `null`	O nome da peça no tribunal (`Sentença`, `Decisão`...).
`data`	data (AAAA-MM-DD) ou `null`	O dia do andamento que gerou a peça.
`url`	texto ou `null`	O endereço da peça no portal do tribunal. ⚠️ Referência, não arquivo: o Citato não guarda o PDF, e o portal pode pedir login para abrir.

Respostas possíveis

Status	Código	Quando
200	—	Sucesso.
400	`requisicao_invalida`	A requisição tentou dizer de qual cliente ela é — cabeçalho como `X-Tenant` ou parâmetro `tenant`. O cliente vem só da chave.
401	`nao_autenticado`	Chave ausente, inválida ou revogada.
403	`sem_permissao`	A chave é válida, mas a API não está habilitada para este cliente — ou a operação não é permitida neste ambiente.
404	`nao_encontrado`	O recurso não está nesta carteira.
422	`entrada_invalida`	Parâmetro ou corpo fora do formato ou do intervalo. O `detalhe` diz qual.
429	`excesso_de_requisicoes`	Passou do limite de requisições por minuto desta chave. Espere os segundos do cabeçalho `Retry-After`.

GET /v1/processos/{cnj}/prazos Exige chave

Os prazos cravados no processo: os em aberto primeiro, pelo vencimento

Os prazos que alguém cravou na carteira, com quem cravou. O Citato não calcula prazo processual: ele aponta o possível prazo no andamento, e a data é de quem a crava.

Parâmetros

Nome	Onde	Tipo	Regras	Descrição
`cnj` Obrigatório	caminho	texto	até 25 caracteres	O número CNJ, com pontuação.
`limite`	consulta	inteiro	1 a 200 · padrão 50	Itens por página, de 1 a 200.
`deslocamento`	consulta	inteiro	a partir de 0 · padrão 0	Quantos itens pular. Para a página seguinte, some o `limite`.

Exemplo

curl "https://citato.blueservice.com.br/v1/processos/0000001-11.2099.8.26.0100/prazos?limite=10" \
  -H "Authorization: Bearer $CITATO_CHAVE"

import os

import requests

resposta = requests.get(
    "https://citato.blueservice.com.br/v1/processos/0000001-11.2099.8.26.0100/prazos",
    params={'limite': 10},
    headers={"Authorization": f"Bearer {os.environ['CITATO_CHAVE']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

const resposta = await fetch(
  "https://citato.blueservice.com.br/v1/processos/0000001-11.2099.8.26.0100/prazos?limite=10",
  {
    headers: { Authorization: `Bearer ${process.env.CITATO_CHAVE}` },
  },
);
if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);
const dados = await resposta.json();

Resposta — em páginas (ver Paginação)

{
  "itens": [
    {
      "id": "3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f",
      "rotulo": "Manifestação sobre a decisão",
      "vence_em": "2099-07-03",
      "observacao": "Prazo fictício do sandbox.",
      "cumprido_em": null,
      "criado_por": "sandbox",
      "criado_em": "2026-10-01T12:12:44.401227Z"
    }
  ],
  "total": 5,
  "limite": 50,
  "deslocamento": 0
}

Campo	Tipo	Descrição
`id`	uuid	Identificador do prazo no Citato.
`rotulo`	texto	O que vence.
`vence_em`	data (AAAA-MM-DD)	A data cravada.
`observacao`	texto ou `null`	A nota de quem cravou.
`cumprido_em`	data (AAAA-MM-DD) ou `null`	Quando foi cumprido. Nulo se está em aberto.
`criado_por`	texto ou `null`	Quem cravou a data.
`criado_em`	data e hora (ISO 8601, UTC)	Quando a data foi cravada.

Respostas possíveis

Status	Código	Quando
200	—	Sucesso.
400	`requisicao_invalida`	A requisição tentou dizer de qual cliente ela é — cabeçalho como `X-Tenant` ou parâmetro `tenant`. O cliente vem só da chave.
401	`nao_autenticado`	Chave ausente, inválida ou revogada.
403	`sem_permissao`	A chave é válida, mas a API não está habilitada para este cliente — ou a operação não é permitida neste ambiente.
404	`nao_encontrado`	O recurso não está nesta carteira.
422	`entrada_invalida`	Parâmetro ou corpo fora do formato ou do intervalo. O `detalhe` diz qual.
429	`excesso_de_requisicoes`	Passou do limite de requisições por minuto desta chave. Espere os segundos do cabeçalho `Retry-After`.

GET /v1/monitores Exige chave

Lista os acompanhamentos da carteira

O que a carteira acompanha — CNPJ, CPF, OAB, razão social ou CNJ —, do mais novo para o mais velho, com quantos processos cada um trouxe.

Parâmetros

Nome	Onde	Tipo	Regras	Descrição
`limite`	consulta	inteiro	1 a 200 · padrão 50	Itens por página, de 1 a 200.
`deslocamento`	consulta	inteiro	a partir de 0 · padrão 0	Quantos itens pular. Para a página seguinte, some o `limite`.
`tipo`	consulta	um de: cnpj, cpf, oab, razao_social, cnj		Só deste tipo.
`ativo`	consulta	booleano		Só os ativos, ou só os pausados.

Exemplo

curl "https://citato.blueservice.com.br/v1/monitores?limite=10" \
  -H "Authorization: Bearer $CITATO_CHAVE"

import os

import requests

resposta = requests.get(
    "https://citato.blueservice.com.br/v1/monitores",
    params={'limite': 10},
    headers={"Authorization": f"Bearer {os.environ['CITATO_CHAVE']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

const resposta = await fetch(
  "https://citato.blueservice.com.br/v1/monitores?limite=10",
  {
    headers: { Authorization: `Bearer ${process.env.CITATO_CHAVE}` },
  },
);
if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);
const dados = await resposta.json();

Resposta — em páginas (ver Paginação)

{
  "itens": [
    {
      "id": "3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f",
      "tipo": "cnpj",
      "valor": "11222333000181",
      "rotulo": "Empresa Fictícia Alfa Ltda",
      "ativo": true,
      "email_alertas": null,
      "processos": 3,
      "criado_em": "2026-10-01T12:12:44.401227Z",
      "criado_por": "API citato_AbC123"
    }
  ],
  "total": 5,
  "limite": 50,
  "deslocamento": 0
}

Campo	Tipo	Descrição
`id`	uuid	Identificador do acompanhamento no Citato.
`tipo`	texto	`cnpj`, `cpf`, `oab`, `razao_social` ou `cnj`.
`valor`	texto	O valor como o Citato o guarda: documento só com dígitos, OAB como `123456SP`, CNJ com pontuação.
`rotulo`	texto ou `null`	O nome legível (ex.: a razão social).
`ativo`	booleano	Pausado (`false`) não entra na descoberta.
`email_alertas`	texto ou `null`	Para onde vão os avisos das novidades deste acompanhamento.
`processos`	inteiro	Quantos processos este acompanhamento trouxe.
`criado_em`	data e hora (ISO 8601, UTC)	Quando foi cadastrado.
`criado_por`	texto ou `null`	Quem cadastrou: o e-mail de quem usou a tela, ou `API` e o prefixo da chave.

Respostas possíveis

Status	Código	Quando
200	—	Sucesso.
400	`requisicao_invalida`	A requisição tentou dizer de qual cliente ela é — cabeçalho como `X-Tenant` ou parâmetro `tenant`. O cliente vem só da chave.
401	`nao_autenticado`	Chave ausente, inválida ou revogada.
403	`sem_permissao`	A chave é válida, mas a API não está habilitada para este cliente — ou a operação não é permitida neste ambiente.
422	`entrada_invalida`	Parâmetro ou corpo fora do formato ou do intervalo. O `detalhe` diz qual.
429	`excesso_de_requisicoes`	Passou do limite de requisições por minuto desta chave. Espere os segundos do cabeçalho `Retry-After`.

POST /v1/monitores Exige chave

Cadastra um acompanhamento (CNPJ, CPF, OAB, razão social ou CNJ)

Repetir o cadastro com o mesmo tipo e valor devolve o que já existe (200), sem duplicar; o novo volta com 201 e o cabeçalho Location. CNPJ, CPF, OAB e razão social entram na descoberta da madrugada, que cobre o Tribunal de Justiça de São Paulo; CNJ entra na carteira na hora e é lido no ciclo seguinte. No sandbox o cadastro funciona, mas os ciclos não passam por lá.

Corpo (JSON)

Campo	Tipo	Regras	Descrição
`tipo` Obrigatório	um de: cnpj, cpf, oab, razao_social, cnj		O que acompanhar.
`valor` Obrigatório	texto	até 100 caracteres	CNPJ ou CPF (com ou sem pontuação, dígito verificador conferido), OAB (`123456SP`, `123456/SP`), razão social (3 a 64 caracteres) ou o número CNJ.
`rotulo`	texto		Um nome legível, opcional.
`email_alertas`	texto		Para onde vão os avisos deste acompanhamento. Sem ele, vão para os donos da carteira.

Exemplo

curl -X POST "https://citato.blueservice.com.br/v1/monitores" \
  -H "Authorization: Bearer $CITATO_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"tipo": "cnpj", "valor": "11.222.333/0001-81", "rotulo": "Empresa Fictícia Alfa Ltda"}'

import os

import requests

resposta = requests.post(
    "https://citato.blueservice.com.br/v1/monitores",
    json={'tipo': 'cnpj', 'valor': '11.222.333/0001-81', 'rotulo': 'Empresa Fictícia Alfa Ltda'},
    headers={"Authorization": f"Bearer {os.environ['CITATO_CHAVE']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

const resposta = await fetch(
  "https://citato.blueservice.com.br/v1/monitores",
  {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.CITATO_CHAVE}`, "Content-Type": "application/json" },
    body: JSON.stringify({"tipo": "cnpj", "valor": "11.222.333/0001-81", "rotulo": "Empresa Fictícia Alfa Ltda"}),
  },
);
if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);
const dados = await resposta.json();

Resposta

{
  "id": "3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f",
  "tipo": "cnpj",
  "valor": "11222333000181",
  "rotulo": "Empresa Fictícia Alfa Ltda",
  "ativo": true,
  "email_alertas": null,
  "processos": 3,
  "criado_em": "2026-10-01T12:12:44.401227Z",
  "criado_por": "API citato_AbC123"
}

Campo	Tipo	Descrição
`id`	uuid	Identificador do acompanhamento no Citato.
`tipo`	texto	`cnpj`, `cpf`, `oab`, `razao_social` ou `cnj`.
`valor`	texto	O valor como o Citato o guarda: documento só com dígitos, OAB como `123456SP`, CNJ com pontuação.
`rotulo`	texto ou `null`	O nome legível (ex.: a razão social).
`ativo`	booleano	Pausado (`false`) não entra na descoberta.
`email_alertas`	texto ou `null`	Para onde vão os avisos das novidades deste acompanhamento.
`processos`	inteiro	Quantos processos este acompanhamento trouxe.
`criado_em`	data e hora (ISO 8601, UTC)	Quando foi cadastrado.
`criado_por`	texto ou `null`	Quem cadastrou: o e-mail de quem usou a tela, ou `API` e o prefixo da chave.

Respostas possíveis

Status	Código	Quando
200	—	Já existia — devolve o mesmo, sem duplicar
201	—	Criado.
400	`requisicao_invalida`	A requisição tentou dizer de qual cliente ela é — cabeçalho como `X-Tenant` ou parâmetro `tenant`. O cliente vem só da chave.
401	`nao_autenticado`	Chave ausente, inválida ou revogada.
403	`sem_permissao`	A chave é válida, mas a API não está habilitada para este cliente — ou a operação não é permitida neste ambiente.
422	`entrada_invalida`	Parâmetro ou corpo fora do formato ou do intervalo. O `detalhe` diz qual.
429	`excesso_de_requisicoes`	Passou do limite de requisições por minuto desta chave. Espere os segundos do cabeçalho `Retry-After`.

GET /v1/monitores/{monitor_id} Exige chave

Um acompanhamento

O acompanhamento pelo id que o cadastro devolveu.

Parâmetros

Nome	Onde	Tipo	Regras	Descrição
`monitor_id` Obrigatório	caminho	uuid		O `id` do acompanhamento.

Exemplo

curl "https://citato.blueservice.com.br/v1/monitores/3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $CITATO_CHAVE"

import os

import requests

resposta = requests.get(
    "https://citato.blueservice.com.br/v1/monitores/3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f",
    headers={"Authorization": f"Bearer {os.environ['CITATO_CHAVE']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

const resposta = await fetch(
  "https://citato.blueservice.com.br/v1/monitores/3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f",
  {
    headers: { Authorization: `Bearer ${process.env.CITATO_CHAVE}` },
  },
);
if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);
const dados = await resposta.json();

Resposta

{
  "id": "3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f",
  "tipo": "cnpj",
  "valor": "11222333000181",
  "rotulo": "Empresa Fictícia Alfa Ltda",
  "ativo": true,
  "email_alertas": null,
  "processos": 3,
  "criado_em": "2026-10-01T12:12:44.401227Z",
  "criado_por": "API citato_AbC123"
}

Campo	Tipo	Descrição
`id`	uuid	Identificador do acompanhamento no Citato.
`tipo`	texto	`cnpj`, `cpf`, `oab`, `razao_social` ou `cnj`.
`valor`	texto	O valor como o Citato o guarda: documento só com dígitos, OAB como `123456SP`, CNJ com pontuação.
`rotulo`	texto ou `null`	O nome legível (ex.: a razão social).
`ativo`	booleano	Pausado (`false`) não entra na descoberta.
`email_alertas`	texto ou `null`	Para onde vão os avisos das novidades deste acompanhamento.
`processos`	inteiro	Quantos processos este acompanhamento trouxe.
`criado_em`	data e hora (ISO 8601, UTC)	Quando foi cadastrado.
`criado_por`	texto ou `null`	Quem cadastrou: o e-mail de quem usou a tela, ou `API` e o prefixo da chave.

Respostas possíveis

Status	Código	Quando
200	—	Sucesso.
400	`requisicao_invalida`	A requisição tentou dizer de qual cliente ela é — cabeçalho como `X-Tenant` ou parâmetro `tenant`. O cliente vem só da chave.
401	`nao_autenticado`	Chave ausente, inválida ou revogada.
403	`sem_permissao`	A chave é válida, mas a API não está habilitada para este cliente — ou a operação não é permitida neste ambiente.
404	`nao_encontrado`	O recurso não está nesta carteira.
422	`entrada_invalida`	Parâmetro ou corpo fora do formato ou do intervalo. O `detalhe` diz qual.
429	`excesso_de_requisicoes`	Passou do limite de requisições por minuto desta chave. Espere os segundos do cabeçalho `Retry-After`.

PATCH /v1/monitores/{monitor_id} Exige chave

Pausa, retoma ou troca o e-mail de um acompanhamento

{"ativo": false} pausa: o acompanhamento sai da descoberta, e os processos que ele já trouxe continuam na carteira. {"ativo": true} retoma. {"email_alertas": "..."} troca o endereço dos avisos; null limpa (os donos do ambiente passam a receber). Só o que vier no corpo muda.

Parâmetros

Nome	Onde	Tipo	Regras	Descrição
`monitor_id` Obrigatório	caminho	uuid		O `id` do acompanhamento.

Corpo (JSON)

Campo	Tipo	Regras	Descrição
`ativo`	booleano		`false` pausa; `true` volta a acompanhar.
`email_alertas`	texto		Para onde vão os avisos deste acompanhamento. `null` limpa — e sem endereço os avisos vão para os donos do ambiente. Vale para as novidades daqui em diante.

Exemplo

curl -X PATCH "https://citato.blueservice.com.br/v1/monitores/3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f" \
  -H "Authorization: Bearer $CITATO_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"ativo": false}'

import os

import requests

resposta = requests.patch(
    "https://citato.blueservice.com.br/v1/monitores/3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f",
    json={'ativo': False},
    headers={"Authorization": f"Bearer {os.environ['CITATO_CHAVE']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

const resposta = await fetch(
  "https://citato.blueservice.com.br/v1/monitores/3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f",
  {
    method: "PATCH",
    headers: { Authorization: `Bearer ${process.env.CITATO_CHAVE}`, "Content-Type": "application/json" },
    body: JSON.stringify({"ativo": false}),
  },
);
if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);
const dados = await resposta.json();

Resposta

{
  "id": "3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f",
  "tipo": "cnpj",
  "valor": "11222333000181",
  "rotulo": "Empresa Fictícia Alfa Ltda",
  "ativo": true,
  "email_alertas": null,
  "processos": 3,
  "criado_em": "2026-10-01T12:12:44.401227Z",
  "criado_por": "API citato_AbC123"
}

Campo	Tipo	Descrição
`id`	uuid	Identificador do acompanhamento no Citato.
`tipo`	texto	`cnpj`, `cpf`, `oab`, `razao_social` ou `cnj`.
`valor`	texto	O valor como o Citato o guarda: documento só com dígitos, OAB como `123456SP`, CNJ com pontuação.
`rotulo`	texto ou `null`	O nome legível (ex.: a razão social).
`ativo`	booleano	Pausado (`false`) não entra na descoberta.
`email_alertas`	texto ou `null`	Para onde vão os avisos das novidades deste acompanhamento.
`processos`	inteiro	Quantos processos este acompanhamento trouxe.
`criado_em`	data e hora (ISO 8601, UTC)	Quando foi cadastrado.
`criado_por`	texto ou `null`	Quem cadastrou: o e-mail de quem usou a tela, ou `API` e o prefixo da chave.

Respostas possíveis

Status	Código	Quando
200	—	Sucesso.
400	`requisicao_invalida`	A requisição tentou dizer de qual cliente ela é — cabeçalho como `X-Tenant` ou parâmetro `tenant`. O cliente vem só da chave.
401	`nao_autenticado`	Chave ausente, inválida ou revogada.
403	`sem_permissao`	A chave é válida, mas a API não está habilitada para este cliente — ou a operação não é permitida neste ambiente.
404	`nao_encontrado`	O recurso não está nesta carteira.
422	`entrada_invalida`	Parâmetro ou corpo fora do formato ou do intervalo. O `detalhe` diz qual.
429	`excesso_de_requisicoes`	Passou do limite de requisições por minuto desta chave. Espere os segundos do cabeçalho `Retry-After`.

GET /v1/monitores/{monitor_id}/processos Exige chave

Os processos que um acompanhamento trouxe

Um processo pode ter vindo por mais de um acompanhamento — o CNPJ da empresa e a OAB do advogado dela —, e aparece em cada um.

Parâmetros

Nome	Onde	Tipo	Regras	Descrição
`monitor_id` Obrigatório	caminho	uuid		O `id` do acompanhamento.
`limite`	consulta	inteiro	1 a 200 · padrão 50	Itens por página, de 1 a 200.
`deslocamento`	consulta	inteiro	a partir de 0 · padrão 0	Quantos itens pular. Para a página seguinte, some o `limite`.

Exemplo

curl "https://citato.blueservice.com.br/v1/monitores/3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f/processos?limite=10" \
  -H "Authorization: Bearer $CITATO_CHAVE"

import os

import requests

resposta = requests.get(
    "https://citato.blueservice.com.br/v1/monitores/3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f/processos",
    params={'limite': 10},
    headers={"Authorization": f"Bearer {os.environ['CITATO_CHAVE']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

const resposta = await fetch(
  "https://citato.blueservice.com.br/v1/monitores/3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f/processos?limite=10",
  {
    headers: { Authorization: `Bearer ${process.env.CITATO_CHAVE}` },
  },
);
if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);
const dados = await resposta.json();

Resposta — em páginas (ver Paginação)

{
  "itens": [
    {
      "id": "3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f",
      "cnj": "0000001-11.2099.8.26.0100",
      "tribunal": "tjsp",
      "origem": "manual",
      "criado_em": "2026-10-01T12:12:44.401227Z",
      "atualizado_em": "2026-10-02T09:41:03.118540Z"
    }
  ],
  "total": 5,
  "limite": 50,
  "deslocamento": 0
}

Campo	Tipo	Descrição
`id`	uuid	Identificador do processo no Citato.
`cnj`	texto	O número do processo no formato CNJ, com pontuação.
`tribunal`	texto ou `null`	A sigla do tribunal, em minúsculas (`tjsp`).
`origem`	texto	Como o processo entrou: `descoberta` (achado automaticamente), `manual` (cadastrado), `importacao`. ⚠️ Vale ler: a descoberta automática cobre um tribunal, então `manual` não é exceção rara.
`criado_em`	data e hora (ISO 8601, UTC)	Quando o processo entrou no Citato.
`atualizado_em`	data e hora (ISO 8601, UTC)	A última alteração do registro no Citato.

Respostas possíveis

Status	Código	Quando
200	—	Sucesso.
400	`requisicao_invalida`	A requisição tentou dizer de qual cliente ela é — cabeçalho como `X-Tenant` ou parâmetro `tenant`. O cliente vem só da chave.
401	`nao_autenticado`	Chave ausente, inválida ou revogada.
403	`sem_permissao`	A chave é válida, mas a API não está habilitada para este cliente — ou a operação não é permitida neste ambiente.
404	`nao_encontrado`	O recurso não está nesta carteira.
422	`entrada_invalida`	Parâmetro ou corpo fora do formato ou do intervalo. O `detalhe` diz qual.
429	`excesso_de_requisicoes`	Passou do limite de requisições por minuto desta chave. Espere os segundos do cabeçalho `Retry-After`.

GET /v1/novidades Exige chave

As novidades da carteira inteira, da mais nova para a mais velha

O que o Citato marcou como novidade, em todos os processos: andamentos e, desde 03/10/2026, intimações publicadas no DJEN (campo natureza) — a rota para quem consulta de tempos em tempos. Use desde com o instante da última consulta para receber só o que chegou depois.

Parâmetros

Nome	Onde	Tipo	Regras	Descrição
`limite`	consulta	inteiro	1 a 200 · padrão 50	Itens por página, de 1 a 200.
`deslocamento`	consulta	inteiro	a partir de 0 · padrão 0	Quantos itens pular. Para a página seguinte, some o `limite`.
`desde`	consulta	data e hora (ISO 8601, UTC)		Só as marcadas a partir deste instante (ISO 8601, com fuso).

Exemplo

curl "https://citato.blueservice.com.br/v1/novidades?limite=10" \
  -H "Authorization: Bearer $CITATO_CHAVE"

import os

import requests

resposta = requests.get(
    "https://citato.blueservice.com.br/v1/novidades",
    params={'limite': 10},
    headers={"Authorization": f"Bearer {os.environ['CITATO_CHAVE']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

const resposta = await fetch(
  "https://citato.blueservice.com.br/v1/novidades?limite=10",
  {
    headers: { Authorization: `Bearer ${process.env.CITATO_CHAVE}` },
  },
);
if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);
const dados = await resposta.json();

Resposta — em páginas (ver Paginação)

{
  "itens": [
    {
      "id": "3f6d2c1e-8a4b-4c1e-9d2f-1a2b3c4d5e6f",
      "ocorrido_em": "2099-06-11",
      "tipo": null,
      "texto": "Decisão: intime-se a parte autora para manifestação no prazo de 15 dias.",
      "fonte": "sandbox",
      "escopo": "cpopg",
      "noticia_em": "2026-10-02T09:41:03.118540Z",
      "cnj": "0000001-11.2099.8.26.0100",
      "natureza": "intimacao"
    }
  ],
  "total": 5,
  "limite": 50,
  "deslocamento": 0
}

Campo	Tipo	Descrição
`id`	uuid	Identificador do movimento no Citato.
`ocorrido_em`	data (AAAA-MM-DD) ou `null`	O DIA do movimento. É data, não instante: as fontes entregam dia, e inventar hora seria inventar precisão.
`tipo`	texto ou `null`	O tipo do movimento, quando a fonte o separa do texto (a base nacional do CNJ separa; o portal do TJ-SP não, e aí vem `null`).
`texto`	texto	O andamento como a fonte o publicou.
`fonte`	texto	De onde veio: `esaj_movimentos` (portal do TJ-SP), `datajud_tjsp` (base nacional do CNJ) ou `sandbox` (fictício).
`escopo`	texto ou `null`	A trilha dentro do processo: `cpopg` e `cposg` (1º e 2º grau no TJ-SP), ou o grau na base nacional (`G1`, `G2`, `JE`).
`noticia_em`	data e hora (ISO 8601, UTC) ou `null`	Quando o acompanhamento classificou este movimento como NOVIDADE, ou `null`. ⚠️ Três estados, não dois: `null` significa não avaliado (movimento importado antes de o acompanhamento existir), e não 'não é novidade'. Quem integrar filtrando por `!= null` recebe as novidades; quem quiser o oposto precisa saber que o `null` mistura as duas coisas.
`cnj`	texto	O processo da novidade.
`natureza`	um de: andamento, intimacao	O que é a novidade: `andamento` (um movimento do processo) ou `intimacao` (uma comunicação publicada no DJEN, com `fonte` = `djen` e `tipo` = o tipo da comunicação). A mesma decisão pode chegar pelas duas: o ato e a publicação dele — e é da publicação que o prazo se conta.

Respostas possíveis

Status	Código	Quando
200	—	Sucesso.
400	`requisicao_invalida`	A requisição tentou dizer de qual cliente ela é — cabeçalho como `X-Tenant` ou parâmetro `tenant`. O cliente vem só da chave.
401	`nao_autenticado`	Chave ausente, inválida ou revogada.
403	`sem_permissao`	A chave é válida, mas a API não está habilitada para este cliente — ou a operação não é permitida neste ambiente.
422	`entrada_invalida`	Parâmetro ou corpo fora do formato ou do intervalo. O `detalhe` diz qual.
429	`excesso_de_requisicoes`	Passou do limite de requisições por minuto desta chave. Espere os segundos do cabeçalho `Retry-After`.

GET /v1/consumo Exige chave

O extrato de consumo do mês, em créditos

O consumo da carteira no mês, em créditos (1 crédito = R$ 1,00): o total, os subtotais por grupo, o resumo por item e o dia a dia. O monitoramento é apurado de hora em hora, pelos dias na carteira; a chamada da API é contada na hora, só a que deu certo. O dia corrente ainda está em andamento. Consultar o consumo não consome. ⚠️ Simulação: sem fatura nem cobrança.

Parâmetros

Nome	Onde	Tipo	Regras	Descrição
`mes`	consulta	texto		O mês, `AAAA-MM`. Sem ele, o mês corrente (horário de Brasília).

Exemplo

curl "https://citato.blueservice.com.br/v1/consumo" \
  -H "Authorization: Bearer $CITATO_CHAVE"

import os

import requests

resposta = requests.get(
    "https://citato.blueservice.com.br/v1/consumo",
    headers={"Authorization": f"Bearer {os.environ['CITATO_CHAVE']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

const resposta = await fetch(
  "https://citato.blueservice.com.br/v1/consumo",
  {
    headers: { Authorization: `Bearer ${process.env.CITATO_CHAVE}` },
  },
);
if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);
const dados = await resposta.json();

Resposta

{
  "mes": "2026-10",
  "total": "2275.276283",
  "simulacao": false,
  "demonstracao": false,
  "grupos": [
    {
      "codigo": "texto",
      "rotulo": "Monitoramento",
      "creditos": "1234.56"
    }
  ],
  "itens": [
    {
      "codigo": "api_processo",
      "rotulo": "Capa do processo (API)",
      "unidade": "chamada",
      "grupo": "api",
      "quantidade": 0,
      "creditos": "texto"
    }
  ],
  "dias": [
    {
      "dia": "texto",
      "creditos": "texto",
      "linhas": [
        {
          "codigo": "monitoramento_processo",
          "quantidade": 0,
          "valor_unitario": "texto",
          "creditos": "texto"
        }
      ]
    }
  ]
}

Campo	Tipo	Descrição
`mes`	texto	O mês do extrato, `AAAA-MM`.
`total`	texto	O total do mês, em créditos.
`simulacao`	booleano	Sempre `true` por enquanto: o extrato é simulado, sem fatura nem cobrança.
`demonstracao`	booleano	Ambiente de demonstração — sem cobrança.
`grupos`	lista de GrupoDoConsumo	Os subtotais por grupo, todos os grupos, inclusive os que deram zero.
`itens`	lista de ItemDoConsumo	O resumo do mês por item consumido.
`dias`	lista de DiaDoConsumo	O dia a dia, do mais novo para o mais velho.

Respostas possíveis

Status	Código	Quando
200	—	Sucesso.
400	`requisicao_invalida`	A requisição tentou dizer de qual cliente ela é — cabeçalho como `X-Tenant` ou parâmetro `tenant`. O cliente vem só da chave.
401	`nao_autenticado`	Chave ausente, inválida ou revogada.
403	`sem_permissao`	A chave é válida, mas a API não está habilitada para este cliente — ou a operação não é permitida neste ambiente.
422	`entrada_invalida`	Parâmetro ou corpo fora do formato ou do intervalo. O `detalhe` diz qual.
429	`excesso_de_requisicoes`	Passou do limite de requisições por minuto desta chave. Espere os segundos do cabeçalho `Retry-After`.

GET /v1/jurisprudencia Exige chave

Pesquisa de jurisprudência a partir de um texto (experimental)

⚠️ Experimental. É prova de conceito: o formato pode mudar, e STF e TST são interfaces não documentadas dos tribunais, que podem mudar ou fechar sem aviso.

Um texto sobre o caso (um parágrafo, ou poucas palavras) vira até três expressões por regra, sem IA; cada expressão vai à fonte na hora e os resultados se juntam, os que batem em mais expressões primeiro. Mande expressoes para usar as suas no lugar das da regra. Nada é guardado.

Fontes: djen (o Diário de Justiça Eletrônico Nacional — o padrão; cobre os tribunais que publicam lá, mas é o Diário, não jurisprudência curada: acórdão, sentença e despacho misturados; do TJ-SP, só a partir de 2025), stf e tst. estado, tribunal, de e ate valem só para o Diário; sem período, os últimos 12 meses. No Diário cada expressão é FRASE EXATA.

Exige habilitação do cliente, feita por quem administra o Citato. Sem ela, 403. Tem limite próprio de pesquisas por minuto, além do limite geral. Não consome créditos.

⚠️ Pode levar dezenas de segundos: use tempo limite de 60 s ou mais. Consulta que falhou vem em consultas com o erro, e o resto segue valendo; se todas falharem, 503.

Parâmetros

Nome	Onde	Tipo	Regras	Descrição
`texto` Obrigatório	consulta	texto	até 2000 caracteres	O texto do caso, de onde saem as expressões.
`fonte`	consulta	um de: djen, stf, tst	padrão djen	De onde pesquisar.
`expressoes`	consulta	lista		Até três expressões, repetindo o parâmetro, no lugar das que a regra tiraria do texto.
`estado`	consulta	texto		A UF: vira o TJ, o TRT e o TRF dela no Diário.
`tribunal`	consulta	texto		A sigla de um tribunal no Diário. Ganha de `estado`.
`de`	consulta	data (AAAA-MM-DD)		Início do período, no Diário.
`ate`	consulta	data (AAAA-MM-DD)		Fim do período, no Diário.
`pagina`	consulta	inteiro	1 a 1000 · padrão 1	A página, de 10 em 10.

Exemplo

curl "https://citato.blueservice.com.br/v1/jurisprudencia?texto=Negativa%C3%A7%C3%A3o+indevida+do+nome+do+consumidor+gera+dano+moral." \
  -H "Authorization: Bearer $CITATO_CHAVE"

import os

import requests

resposta = requests.get(
    "https://citato.blueservice.com.br/v1/jurisprudencia",
    params={'texto': 'Negativação indevida do nome do consumidor gera dano moral.'},
    headers={"Authorization": f"Bearer {os.environ['CITATO_CHAVE']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

const resposta = await fetch(
  "https://citato.blueservice.com.br/v1/jurisprudencia?texto=Negativa%C3%A7%C3%A3o+indevida+do+nome+do+consumidor+gera+dano+moral.",
  {
    headers: { Authorization: `Bearer ${process.env.CITATO_CHAVE}` },
  },
);
if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);
const dados = await resposta.json();

Resposta

{
  "fonte": "djen",
  "pagina": 1,
  "total": 52,
  "total_minimo": true,
  "tem_mais": true,
  "expressoes": [
    "dano moral",
    "negativação indevida"
  ],
  "consultas": [
    {
      "tribunal": "TJGO",
      "expressao": "dano moral",
      "total": 52,
      "erro": null
    }
  ],
  "itens": [
    {
      "fonte": "djen",
      "tribunal": "TJGO",
      "processo": "0000001-11.2099.8.26.0100",
      "trecho": "... a inscrição indevida em cadastro de inadimplentes configura dano moral presumido, dispensada a prova do prejuízo ...",
      "link": null,
      "data": "2099-06-11",
      "classe": "",
      "orgao": "1ª Turma Recursal Fictícia",
      "relator": "",
      "tipo": "Acórdão",
      "acertos": 2
    }
  ]
}

Campo	Tipo	Descrição
`fonte`	texto
`pagina`	inteiro
`total`	inteiro	Total de documentos, somando as consultas.
`total_minimo`	booleano	`true` quando o total é "pelo menos": a fonte conta até um teto, ou é a soma de várias consultas, que podem repetir documento.
`tem_mais`	booleano	Há outra página adiante.
`expressoes`	lista	As expressões usadas — as que vieram, ou as que a regra tirou do texto.
`consultas`	lista de ConsultaFeita	Cada ida à fonte, com o erro se houve.
`itens`	lista de DecisaoAchada	Os documentos, os de mais acertos primeiro.

Respostas possíveis

Status	Código	Quando
200	—	Sucesso.
400	`requisicao_invalida`	A requisição tentou dizer de qual cliente ela é — cabeçalho como `X-Tenant` ou parâmetro `tenant`. O cliente vem só da chave.
401	`nao_autenticado`	Chave ausente, inválida ou revogada.
403	`sem_permissao`	A chave é válida, mas a API não está habilitada para este cliente — ou a operação não é permitida neste ambiente.
422	`entrada_invalida`	Parâmetro ou corpo fora do formato ou do intervalo. O `detalhe` diz qual.
429	`excesso_de_requisicoes`	Passou do limite de requisições por minuto desta chave. Espere os segundos do cabeçalho `Retry-After`.
503	`fonte_indisponivel`	A fonte externa não respondeu a nenhuma consulta. Só a pesquisa de jurisprudência vai a uma fonte na hora; tente de novo em instantes.

GET /v1/indices Exige chave

A série mensal de um índice de correção e o fator até a data-base

A mesma Tabela Prática da tela: a variação de cada mês e o fator acumulado até a última competência publicada. Índices: IPCA, INPC, IPCA-E (IPCA-15), IGP-M, SELIC e TR.

Gratuita: o dado é público. ⚠️ O fator corrige só pelo índice — sem juros, sem expurgos, sem tabela prática de tribunal.

Parâmetros

Nome	Onde	Tipo	Regras	Descrição
`indice`	consulta	um de: ipca, inpc, ipca_e, igpm, selic, tr	padrão ipca	O índice. Sem ele, o IPCA.
`de`	consulta	data (AAAA-MM-DD)		A competência inicial (AAAA-MM-DD; vale o mês). Sem ela, desde o início.
`ate`	consulta	data (AAAA-MM-DD)		A competência final (AAAA-MM-DD; vale o mês). Sem ela, até a última.

Exemplo

curl "https://citato.blueservice.com.br/v1/indices" \
  -H "Authorization: Bearer $CITATO_CHAVE"

import os

import requests

resposta = requests.get(
    "https://citato.blueservice.com.br/v1/indices",
    headers={"Authorization": f"Bearer {os.environ['CITATO_CHAVE']}"},
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

const resposta = await fetch(
  "https://citato.blueservice.com.br/v1/indices",
  {
    headers: { Authorization: `Bearer ${process.env.CITATO_CHAVE}` },
  },
);
if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);
const dados = await resposta.json();

Resposta

{
  "indice": "ipca",
  "indice_nome": "IPCA",
  "publicado_por": "IBGE",
  "corrigido_ate": "2026-09-01",
  "pendente": null,
  "competencias": [
    {
      "competencia": "2026-08-01",
      "variacao": "0.4400",
      "fator": "1.004400"
    }
  ]
}

Campo	Tipo	Descrição
`indice`	texto	O índice.
`indice_nome`	texto	O nome do índice.
`publicado_por`	texto	Quem publica. O Citato lê tudo do SGS do Banco Central, mas o BACEN só repassa os índices de preço.
`corrigido_ate`	data (AAAA-MM-DD) ou `null`	A última competência que o Citato tem — a data-base dos fatores. Nula se a série ainda não foi lida.
`pendente`	data (AAAA-MM-DD) ou `null`	A competência que já devia estar publicada e ainda não está. Nula quando a série está em dia.
`competencias`	lista de CompetenciaDoIndice	As competências do intervalo pedido, da mais nova para a mais antiga.

Respostas possíveis

Status	Código	Quando
200	—	Sucesso.
400	`requisicao_invalida`	A requisição tentou dizer de qual cliente ela é — cabeçalho como `X-Tenant` ou parâmetro `tenant`. O cliente vem só da chave.
401	`nao_autenticado`	Chave ausente, inválida ou revogada.
403	`sem_permissao`	A chave é válida, mas a API não está habilitada para este cliente — ou a operação não é permitida neste ambiente.
422	`entrada_invalida`	Parâmetro ou corpo fora do formato ou do intervalo. O `detalhe` diz qual.
429	`excesso_de_requisicoes`	Passou do limite de requisições por minuto desta chave. Espere os segundos do cabeçalho `Retry-After`.

GET /saude Sem chave

A aplicação está de pé?

Responde sem chave de API. Serve para monitorar a disponibilidade.

Exemplo

curl "https://citato.blueservice.com.br/saude"

import os

import requests

resposta = requests.get(
    "https://citato.blueservice.com.br/saude",
    timeout=30,
)
resposta.raise_for_status()
dados = resposta.json()

const resposta = await fetch(
  "https://citato.blueservice.com.br/saude",
);
if (!resposta.ok) throw new Error(`HTTP ${resposta.status}`);
const dados = await resposta.json();

Resposta

{
  "estado": "ok",
  "versao": "v1"
}

Respostas possíveis

Status	Código	Quando
200	—	Sucesso.