{"components":{"responses":{},"schemas":{"CacheHitResponse":{"description":"Response returned when cached data exists (HTTP 200). Always includes `consult_id` for referencing the consult later. When `stale` is true, a background refresh has been triggered.","example":{"data":{"consult_id":"550e8400-e29b-41d4-a716-446655440000","courts":[{"court":"TJSP","extracted_at":"2026-03-04T14:30:00Z","processes":[{"area":"Civel","assuntos":[{"cod_assunto":7619,"ds_assunto":"Indenizacao por Dano Moral"}],"classe":"Procedimento Comum Civel","competencia":"1a Vara Civel","court":"TJSP","distribuido_em":"15/01/2024","extracted_at":"2026-03-04T14:30:00Z","instance":"1","movimentos":[{"data_movimento":"01/03/2024","descricao":"Juntada de Peticao","movimento":"60"}],"numero_processo":"0001234-89.2024.8.26.0100","numero_processo_unico":"1234567-89.2024.8.26.0100","partes":[{"nome":"Joao da Silva","representante":"Dr. Advogado OAB/SP 12345","tipo":"Autor"},{"nome":"Empresa XYZ Ltda","representante":"Dr. Defensor OAB/SP 67890","tipo":"Reu"}],"situacao":"Em andamento","system":"esaj","uf":"SP","url_processo":"https://esaj.tjsp.jus.br/cpopg/show.do?processo.codigo=1234567890","valor_causa":"R$ 50.000,00"}],"source":"cache","stale":false,"system":"esaj"}],"document":"529.982.247-25","source":"cache","stale":false}},"properties":{"data":{"description":"Cached consult data with per-court freshness information.","properties":{"consult_id":{"description":"Unique identifier for this consult. Use to poll results via `GET /api/v1/consults/:id`.","format":"uuid","type":"string"},"courts":{"description":"Per-court cached data with freshness indicators.","items":{"properties":{"court":{"description":"Court code (e.g., `TJSP`, `TJRJ`).","type":"string"},"extracted_at":{"description":"When the cached data was last extracted.","format":"date-time","nullable":true,"type":"string"},"processes":{"description":"Extracted process records.","items":{"$ref":"#/components/schemas/ProcessRecord"},"type":"array"},"source":{"description":"`cache` when data is from cache, `processing` when data extraction is in progress.","enum":["cache","processing"],"type":"string"},"stale":{"description":"Whether this court's data is older than 2 days.","type":"boolean"},"system":{"description":"Court software system (e.g., `esaj`, `pje`, `tribunal`).","type":"string"}},"required":["court","system","source","stale","processes"],"type":"object"},"type":"array"},"document":{"description":"The CPF document that was searched.","type":"string"},"source":{"description":"`cache` — data served from cache.","enum":["cache"],"type":"string"},"stale":{"description":"`false` when all data is fresh (< 2 days). `true` when some data is older than 2 days and a background refresh was triggered.","type":"boolean"}},"required":["source","stale","consult_id","document","courts"],"type":"object"}},"required":["data"],"title":"CacheHitResponse","type":"object"},"ConsultActionResponse":{"description":"Response for consult actions (cancel, reprocess). Returns the consult ID and updated status.","example":{"data":{"id":"550e8400-e29b-41d4-a716-446655440000","status":"canceled"}},"properties":{"data":{"description":"Consult action result.","properties":{"id":{"description":"Consult unique identifier.","format":"uuid","type":"string"},"status":{"description":"Updated consult status. `canceled` after cancel action, `in_progress` after reprocess.","enum":["canceled","in_progress"],"type":"string"}},"required":["id","status"],"type":"object"}},"required":["data"],"title":"ConsultActionResponse","type":"object"},"ConsultCreatedResponse":{"description":"Response returned when a new consult is created and scraping is triggered (HTTP 202 Accepted).","example":{"data":{"consult_id":"550e8400-e29b-41d4-a716-446655440000","courts":[{"court":"TJSP","status":"queued","system":"esaj"},{"court":"TJRJ","status":"queued","system":"tribunal"}],"document":"529.982.247-25","source":"processing"}},"properties":{"data":{"description":"Consult creation data with enqueued court searches.","properties":{"consult_id":{"description":"Unique consult identifier. Use this to poll for results.","format":"uuid","type":"string"},"courts":{"description":"List of court searches with their initial status.","items":{"properties":{"court":{"description":"Court code (e.g., `TJSP`, `TJRJ`).","type":"string"},"status":{"description":"Initial status of the court search.","enum":["queued"],"type":"string"},"system":{"description":"Court software system (e.g., `esaj`, `pje`, `tribunal`).","type":"string"}},"required":["court","system","status"],"type":"object"},"type":"array"},"document":{"description":"The CPF document that was searched.","type":"string"},"source":{"description":"`processing` — scraping has been triggered for all requested courts.","enum":["processing"],"type":"string"}},"required":["source","consult_id","document","courts"],"type":"object"}},"required":["data"],"title":"ConsultCreatedResponse","type":"object"},"ConsultDetailResponse":{"description":"Detailed consult response with court search statuses and extracted process data.","example":{"data":{"courts":[{"court":"TJSP","error_message":null,"finished_at":"2026-03-02T10:00:35Z","processes":[{"area":"Civel","assuntos":[{"cod_assunto":7619,"ds_assunto":"Indenizacao por Dano Moral"}],"classe":"Procedimento Comum Civel","competencia":"1a Vara Civel","court":"TJSP","distribuido_em":"15/01/2024","extracted_at":"2026-03-02T10:00:30Z","instance":"1","movimentos":[{"data_movimento":"01/03/2024","descricao":"Juntada de Peticao","movimento":"60"}],"numero_processo":"0001234-89.2024.8.26.0100","numero_processo_unico":"1234567-89.2024.8.26.0100","partes":[{"nome":"Joao da Silva","representante":"Dr. Advogado OAB/SP 12345","tipo":"Autor"},{"nome":"Empresa XYZ Ltda","representante":"Dr. Defensor OAB/SP 67890","tipo":"Reu"}],"situacao":"Em andamento","system":"esaj","uf":"SP","url_processo":"https://esaj.tjsp.jus.br/cpopg/show.do?processo.codigo=1234567890","valor_causa":"R$ 50.000,00"}],"started_at":"2026-03-02T10:00:05Z","status":"completed","system":"esaj"},{"court":"TJRJ","error_message":"Connection timeout after 30s","finished_at":"2026-03-02T10:00:35Z","processes":[],"started_at":"2026-03-02T10:00:05Z","status":"exhausted","system":"tribunal"}],"document":"529.982.247-25","id":"550e8400-e29b-41d4-a716-446655440000","inserted_at":"2026-03-02T10:00:00Z","status":"done"}},"properties":{"data":{"description":"Full consult details including all court search results.","properties":{"courts":{"description":"Court search results with processing details.","items":{"properties":{"court":{"description":"Court code (e.g., `TJSP`).","type":"string"},"error_message":{"description":"Error details when in a failed or exhausted state.","nullable":true,"type":"string"},"finished_at":{"description":"When processing completed (null if not finished).","format":"date-time","nullable":true,"type":"string"},"processes":{"description":"Extracted lawsuit data. Empty while processing.","items":{"$ref":"#/components/schemas/ProcessRecord"},"type":"array"},"started_at":{"description":"When processing began (null if not started).","format":"date-time","nullable":true,"type":"string"},"status":{"description":"Court search processing status.","enum":["queued","running","completed","failed","exhausted","unavailable","canceled"],"type":"string"},"system":{"description":"Court software system.","type":"string"}},"required":["court","system","status","processes"],"type":"object"},"type":"array"},"document":{"description":"The CPF document that was searched.","type":"string"},"id":{"description":"Consult unique identifier.","format":"uuid","type":"string"},"inserted_at":{"description":"Consult creation timestamp in UTC (ISO 8601).","format":"date-time","type":"string"},"status":{"description":"Current consult lifecycle status.","enum":["pending","in_progress","done","canceled"],"type":"string"}},"required":["id","document","status","inserted_at","courts"],"type":"object"}},"required":["data"],"title":"ConsultDetailResponse","type":"object"},"CourtSourcesResponse":{"description":"List of publicly visible court source endpoints across ESAJ, PJE, and Tribunal-specific systems with operational status.","example":{"data":[{"court_code":"TJSP","name":"Tribunal de Justica de Sao Paulo","state":"SP","status":"active","system":"esaj"},{"court_code":"TJGO","name":"Tribunal de Justica de Goias","state":"GO","status":"active","system":"projudi"},{"court_code":"TJMT","name":"Tribunal de Justica de Mato Grosso","state":"MT","status":"coming_soon","system":"clickjud"}]},"properties":{"data":{"description":"Array of court source objects.","items":{"properties":{"court_code":{"description":"Unique court code used when creating consults (e.g., `TJSP`, `TJRJ`, `TRF1`).","type":"string"},"name":{"description":"Human-readable court name in Portuguese (e.g., `Tribunal de Justica de Sao Paulo`).","type":"string"},"state":{"description":"Brazilian state code (e.g., `SP`, `RJ`) or federal region.","type":"string"},"status":{"description":"`active`: operational, can be searched. `unavailable`: temporarily down, can be selected but may fail. `coming_soon`: scraper under development, cannot be searched yet.","enum":["active","unavailable","coming_soon"],"type":"string"},"system":{"description":"Court software system. Some courts appear in multiple systems (e.g., TJBA has both `esaj` and `pje`).","enum":["esaj","pje","tucujuris","projudi","clickjud","eproc","consulta_unificada","tribunal"],"type":"string"}},"required":["court_code","system","name","state","status"],"type":"object"},"type":"array"}},"required":["data"],"title":"CourtSourcesResponse","type":"object"},"CreateConsultRequest":{"description":"Request body for creating a new consult. A consult searches a CPF across one or more courts. The system always searches all instances (1st and 2nd) and all legal areas.","example":{"courts":["TJSP","TJRJ","TJBA"],"document":"529.982.247-25","force_refresh":false},"properties":{"courts":{"description":"List of court codes to search (e.g., `[\"TJSP\", \"TJRJ\"]`). Use `GET /api/v1/courts` to discover available codes. One court code may resolve to multiple systems (e.g., TJBA has both ESAJ and PJE). Courts with status `not_implemented` will be rejected.","items":{"type":"string"},"minItems":1,"type":"array"},"document":{"description":"CPF number — accepts masked `NNN.NNN.NNN-NN` or unmasked `NNNNNNNNNNN` (11 digits). Must be a valid CPF with correct check digits. Stored and returned in masked format.","pattern":"^(\\d{3}\\.\\d{3}\\.\\d{3}-\\d{2}|\\d{11})$","type":"string"},"force_refresh":{"default":false,"description":"When `true`, skips the cache and always triggers new scraping. Costs 5x credits per court (5 credits instead of 1). Default: `false`.","type":"boolean"}},"required":["document","courts"],"title":"CreateConsultRequest","type":"object"},"HealthResponse":{"description":"Health check response with critical dependency and external service checks. Uses generic names to avoid exposing implementation details. Returns HTTP 200 when all critical checks pass, HTTP 503 when any critical check fails.","example":{"checks":{"database":"ok","queue":"ok"},"external_services":{"email":"not_configured","payment":"ok","solver":"not_configured"},"status":"healthy","version":"0.12.0"},"properties":{"checks":{"description":"Critical dependency health checks. All must be `ok` for healthy status.","properties":{"database":{"description":"Database connectivity.","enum":["ok","error"],"type":"string"},"queue":{"description":"Background job queue processing.","enum":["ok","error"],"type":"string"}},"required":["database","queue"],"type":"object"},"external_services":{"description":"External service reachability checks. Do not affect overall HTTP status code.","properties":{"email":{"description":"Email service. `ok` if reachable, `not_configured` when not configured.","enum":["ok","error","not_configured"],"type":"string"},"payment":{"description":"Payment gateway. `ok` if reachable, `not_configured` when API key is not set.","enum":["ok","error","not_configured"],"type":"string"},"solver":{"description":"CAPTCHA solver service. `ok` if reachable, `not_configured` when API key is not set.","enum":["ok","error","not_configured"],"type":"string"}},"required":["payment","solver","email"],"type":"object"},"status":{"description":"Overall system status. `healthy` when all critical checks pass, `degraded` when any fails.","enum":["healthy","degraded"],"type":"string"},"version":{"description":"Application version (semantic versioning).","type":"string"}},"required":["status","version","checks","external_services"],"title":"HealthResponse","type":"object"},"ProblemDetails":{"description":"RFC 7807 Problem Details response. All API errors follow this format with Content-Type `application/problem+json`.","example":{"detail":"Consult not found","instance":"/api/v1/consults/550e8400-e29b-41d4-a716-446655440000","status":404,"title":"Not Found","type":"https://vigilant.trackjud.com.br/errors/not-found"},"properties":{"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","type":"string"},"errors":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"Field-level validation errors. Only present for 422 Unprocessable Entity responses.","nullable":true,"type":"object"},"instance":{"description":"The request path that caused the error.","type":"string"},"status":{"description":"The HTTP status code for this occurrence of the problem.","type":"integer"},"title":{"description":"A short, human-readable summary of the problem type.","type":"string"},"type":{"description":"A URI that identifies the problem type. Under `https://vigilant.trackjud.com.br/errors/`.","format":"uri","type":"string"}},"required":["type","title","status","detail"],"title":"ProblemDetails","type":"object"},"ProcessRecord":{"description":"Extracted lawsuit data from a Brazilian court. Each process represents a lawsuit/legal case with its parties, movements, and subjects.","example":{"area":"Civel","assuntos":[{"cod_assunto":7619,"cod_complemento":null,"ds_assunto":"Indenizacao por Dano Moral","ds_assunto_completo":"DIREITO CIVIL | Responsabilidade Civil | Indenizacao por Dano Moral"}],"classe":"Procedimento Comum Civel","competencia":"1a Vara Civel","court":"TJSP","distribuido_em":"15/01/2024","extracted_at":"2026-03-04T14:30:00Z","instance":"1","movimentos":[{"data_movimento":"01/03/2024","descricao":"Juntada de Peticao","movimento":"60"},{"data_movimento":"15/01/2024","descricao":"Distribuido por Sorteio","movimento":"26"}],"numero_processo":"0001234-89.2024.8.26.0100","numero_processo_antigo":null,"numero_processo_unico":"1234567-89.2024.8.26.0100","partes":[{"nome":"Joao da Silva","representante":"Dr. Advogado OAB/SP 12345","tipo":"Autor"},{"nome":"Empresa XYZ Ltda","representante":"Dr. Defensor OAB/SP 67890","tipo":"Reu"}],"situacao":"Em andamento","system":"esaj","uf":"SP","url_processo":"https://esaj.tjsp.jus.br/cpopg/show.do?processo.codigo=1234567890","valor_causa":"R$ 50.000,00"},"properties":{"area":{"description":"Legal area (e.g., `Civel`, `Criminal`).","nullable":true,"type":"string"},"assuntos":{"description":"Legal subjects/topics classifying the lawsuit.","items":{"properties":{"cod_assunto":{"description":"Subject code.","nullable":true,"type":"integer"},"cod_complemento":{"description":"Complement code.","nullable":true,"type":"integer"},"ds_assunto":{"description":"Short subject description.","nullable":true,"type":"string"},"ds_assunto_completo":{"description":"Full subject description with hierarchy.","nullable":true,"type":"string"}},"type":"object"},"type":"array"},"classe":{"description":"Case class/category (e.g., `Procedimento Comum Civel`, `Execucao Fiscal`).","nullable":true,"type":"string"},"competencia":{"description":"Jurisdiction/competence (e.g., `1a Vara Civel`, `2a Vara Criminal`).","nullable":true,"type":"string"},"court":{"description":"Court code (e.g., `TJSP`, `TJRJ`).","type":"string"},"distribuido_em":{"description":"Distribution date (when the case was assigned to a judge/court).","nullable":true,"type":"string"},"extracted_at":{"description":"When this record was extracted from the court website (ISO 8601 UTC).","format":"date-time","type":"string"},"fase":{"description":"Current phase of the process.","nullable":true,"type":"string"},"impedimento":{"description":"Impediment information, if any.","nullable":true,"type":"string"},"instance":{"description":"Court instance. `1` = 1st instance (trial court), `2` = 2nd instance (appeals court).","enum":["1","2"],"type":"string"},"julgamento":{"description":"Judgment information, if available.","nullable":true,"type":"string"},"movimentos":{"description":"Chronological case movements (filings, hearings, decisions, etc.).","items":{"properties":{"data_movimento":{"description":"Date of the movement (e.g., `01/03/2024`).","type":"string"},"descricao":{"description":"Description of what happened.","type":"string"},"movimento":{"description":"Movement code/type identifier.","nullable":true,"type":"string"}},"required":["data_movimento","descricao"],"type":"object"},"type":"array"},"numero_processo":{"description":"Court's own process number (may differ from CNJ number).","nullable":true,"type":"string"},"numero_processo_antigo":{"description":"Legacy process number, if the case was migrated from an older system.","nullable":true,"type":"string"},"numero_processo_unico":{"description":"CNJ standardized unique process number. Format: `NNNNNNN-DD.AAAA.J.TR.OOOO`. This field is always present — processes without a valid CNJ number are rejected.","type":"string"},"partes":{"description":"Parties involved in the lawsuit (plaintiffs, defendants, lawyers, etc.).","items":{"properties":{"bairro":{"description":"Neighborhood.","nullable":true,"type":"string"},"cep":{"description":"Postal/ZIP code.","nullable":true,"type":"string"},"filiacao":{"description":"Parentage/family information.","nullable":true,"type":"string"},"logradouro":{"description":"Street address.","nullable":true,"type":"string"},"nome":{"description":"Full name of the party.","type":"string"},"representante":{"description":"Legal representative / lawyer name and OAB registration.","nullable":true,"type":"string"},"tipo":{"description":"Party role (e.g., `Autor`, `Reu`, `Advogado`, `Requerente`, `Requerido`).","type":"string"}},"required":["tipo","nome"],"type":"object"},"type":"array"},"procedencia":{"description":"Provenance information.","nullable":true,"type":"string"},"processo_origem":{"description":"Origin process reference, if this case was derived from another.","nullable":true,"type":"string"},"processos_dependentes":{"description":"Related or dependent process numbers.","items":{"type":"string"},"type":"array"},"segredo":{"description":"Whether the case is under secrecy (`Sim` / `Nao`).","nullable":true,"type":"string"},"sigiloso":{"description":"Confidentiality flag.","nullable":true,"type":"string"},"situacao":{"description":"Current situation/status of the case in court (e.g., `Em andamento`, `Arquivado`).","nullable":true,"type":"string"},"system":{"description":"Court software system used for extraction (e.g., `esaj`, `pje`).","type":"string"},"tipo_processo":{"description":"Process type classification.","nullable":true,"type":"string"},"uf":{"description":"Brazilian state code (e.g., `SP`, `RJ`).","type":"string"},"url_processo":{"description":"Full absolute URL to the process page on the court website (e.g., `https://esaj.tjsp.jus.br/cpopg/show.do?...`).","nullable":true,"type":"string"},"valor_causa":{"description":"Case monetary value (e.g., `R$ 50.000,00`).","nullable":true,"type":"string"}},"required":["numero_processo_unico","instance","court","system","uf","partes","movimentos","assuntos"],"title":"ProcessRecord","type":"object"}},"securitySchemes":{"BearerAuth":{"description":"API key authentication. Generate keys from the user dashboard. Include in requests as `Authorization: Bearer <api_key>`.","scheme":"bearer","type":"http"}}},"externalDocs":{"description":"TrackJud blog — concepts, use cases, and case studies","url":"https://trackjud.com.br/blog"},"info":{"contact":{"email":"support@trackjud.com.br","name":"Vigilant API Support","url":"https://vigilant.trackjud.com.br"},"description":"Vigilant is a high-throughput Brazilian court process scraping API. Submit a CPF (Brazilian individual taxpayer ID) and a list of courts, and Vigilant searches all instances and legal areas across multiple court sources (ESAJ, PJE, Tribunal-specific systems), returning structured lawsuit data in a single response.\n\nNew here? Read the **Getting Started** section first — it explains how to authenticate, make your first call, interpret the response shape, and the Brazilian legal terminology used across the API.\n\nAll errors follow [RFC 7807 Problem Details](https://www.rfc-editor.org/rfc/rfc7807) with `Content-Type: application/problem+json`.\n","license":{"name":"Proprietary"},"title":"Vigilant API","version":"0.36.0"},"openapi":"3.0.0","paths":{"/api/health":{"get":{"callbacks":{},"description":"Returns application health status, version, and basic dependency checks. Returns HTTP 200 when all checks pass, HTTP 503 when any check fails.","operationId":"healthCheck","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}},"description":"Healthy status"},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}},"description":"Degraded status"}},"summary":"Health check","tags":["Health"],"x-codeSamples":[{"label":"cURL","lang":"curl","source":"curl https://vigilant.trackjud.com.br/api/health"},{"label":"Python","lang":"Python","source":"import requests\n\nr = requests.get(\"https://vigilant.trackjud.com.br/api/health\")\nprint(r.status_code, r.json())"},{"label":"JavaScript","lang":"JavaScript","source":"const r = await fetch(\"https://vigilant.trackjud.com.br/api/health\");\nconsole.log(r.status, await r.json());"}]}},"/api/v1/consults":{"get":{"callbacks":{},"description":"Returns a paginated list of the authenticated user's consults.","operationId":"listConsults","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Paginated consults list"}},"security":[{"BearerAuth":[]}],"summary":"List consults","tags":["Consults"],"x-codeSamples":[{"label":"cURL","lang":"curl","source":"curl https://vigilant.trackjud.com.br/api/v1/consults \\\n  -H \"Authorization: Bearer vgl_your_api_key\""},{"label":"Python","lang":"Python","source":"import requests\n\nr = requests.get(\n    \"https://vigilant.trackjud.com.br/api/v1/consults\",\n    headers={\"Authorization\": \"Bearer vgl_your_api_key\"},\n)\nprint(r.json())"},{"label":"JavaScript","lang":"JavaScript","source":"const r = await fetch(\"https://vigilant.trackjud.com.br/api/v1/consults\", {\n  headers: { \"Authorization\": \"Bearer vgl_your_api_key\" }\n});\nconsole.log(await r.json());"}]},"post":{"callbacks":{},"description":"Creates a new consult for the given CPF document across one or more courts. Credits are deducted atomically — each court costs 1 credit (5x with `force_refresh: true`). The system always searches all instances (1st and 2nd) and all legal areas. Returns cached data immediately (200) when fresh records exist, or 202 when new data extraction is required.","operationId":"createConsult","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateConsultRequest"}}},"description":"Consult params","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheHitResponse"}}},"description":"Cache hit — data returned immediately"},"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsultCreatedResponse"}}},"description":"Consult created and searches enqueued"},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}},"description":"Invalid input"},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}},"description":"Missing or invalid API key"},"402":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}},"description":"Insufficient credits"},"422":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}},"description":"Validation error"}},"security":[{"BearerAuth":[]}],"summary":"Create a consult","tags":["Consults"],"x-codeSamples":[{"label":"cURL","lang":"curl","source":"curl -X POST https://vigilant.trackjud.com.br/api/v1/consults \\\n  -H \"Authorization: Bearer vgl_your_api_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"document\": \"529.982.247-25\",\n    \"courts\": [\"TJSP\", \"TJMG\"]\n  }'"},{"label":"Python","lang":"Python","source":"import requests\n\nr = requests.post(\n    \"https://vigilant.trackjud.com.br/api/v1/consults\",\n    headers={\"Authorization\": \"Bearer vgl_your_api_key\"},\n    json={\n        \"document\": \"529.982.247-25\",\n        \"courts\": [\"TJSP\", \"TJMG\"],\n    },\n)\nprint(r.status_code, r.json())"},{"label":"JavaScript","lang":"JavaScript","source":"const r = await fetch(\"https://vigilant.trackjud.com.br/api/v1/consults\", {\n  method: \"POST\",\n  headers: {\n    \"Authorization\": \"Bearer vgl_your_api_key\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: JSON.stringify({\n    document: \"529.982.247-25\",\n    courts: [\"TJSP\", \"TJMG\"]\n  })\n});\nconsole.log(r.status, await r.json());"}]}},"/api/v1/consults/{id}":{"get":{"callbacks":{},"description":"Returns the current status of a consult and its court searches with extracted process data.","operationId":"showConsult","parameters":[{"description":"Consult UUID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsultDetailResponse"}}},"description":"Consult details"},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}},"description":"Invalid ID format"},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}},"description":"Missing or invalid API key"},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}},"description":"Consult not found"}},"security":[{"BearerAuth":[]}],"summary":"Get consult status","tags":["Consults"],"x-codeSamples":[{"label":"cURL","lang":"curl","source":"curl https://vigilant.trackjud.com.br/api/v1/consults/CONSULT_ID \\\n  -H \"Authorization: Bearer vgl_your_api_key\""},{"label":"Python","lang":"Python","source":"import requests\n\nconsult_id = \"...\"\nr = requests.get(\n    f\"https://vigilant.trackjud.com.br/api/v1/consults/{consult_id}\",\n    headers={\"Authorization\": \"Bearer vgl_your_api_key\"},\n)\nprint(r.json())"},{"label":"JavaScript","lang":"JavaScript","source":"const consultId = \"...\";\nconst r = await fetch(`https://vigilant.trackjud.com.br/api/v1/consults/${consultId}`, {\n  headers: { \"Authorization\": \"Bearer vgl_your_api_key\" }\n});\nconsole.log(await r.json());"}]}},"/api/v1/consults/{id}/cancel":{"put":{"callbacks":{},"description":"Cancels a consult and all its non-terminal court searches. Only pending or in-progress consults can be canceled. User-initiated cancels do not trigger credit refunds.","operationId":"cancelConsult","parameters":[{"description":"Consult UUID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsultActionResponse"}}},"description":"Consult canceled"},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}},"description":"Invalid ID format"},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}},"description":"Consult not found"},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}},"description":"Already in terminal state"}},"security":[{"BearerAuth":[]}],"summary":"Cancel a consult","tags":["Consults"],"x-codeSamples":[{"label":"cURL","lang":"curl","source":"curl -X PUT https://vigilant.trackjud.com.br/api/v1/consults/CONSULT_ID/cancel \\\n  -H \"Authorization: Bearer vgl_your_api_key\""},{"label":"Python","lang":"Python","source":"import requests\n\nconsult_id = \"...\"\nr = requests.put(\n    f\"https://vigilant.trackjud.com.br/api/v1/consults/{consult_id}/cancel\",\n    headers={\"Authorization\": \"Bearer vgl_your_api_key\"},\n)\nprint(r.json())"},{"label":"JavaScript","lang":"JavaScript","source":"const consultId = \"...\";\nconst r = await fetch(\n  `https://vigilant.trackjud.com.br/api/v1/consults/${consultId}/cancel`,\n  {\n    method: \"PUT\",\n    headers: { \"Authorization\": \"Bearer vgl_your_api_key\" }\n  }\n);\nconsole.log(await r.json());"}]}},"/api/v1/consults/{id}/reprocess":{"post":{"callbacks":{},"description":"Re-enqueues failed or exhausted court searches within a done consult. Only court searches in terminal error states (exhausted, unavailable) are reprocessed.","operationId":"reprocessConsult","parameters":[{"description":"Consult UUID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsultActionResponse"}}},"description":"Consult reprocessed"},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}},"description":"Invalid ID format"},"402":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}},"description":"Insufficient credits to reprocess"},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}},"description":"Consult not found"},"409":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}},"description":"No reprocessable searches"}},"security":[{"BearerAuth":[]}],"summary":"Reprocess a consult","tags":["Consults"],"x-codeSamples":[{"label":"cURL","lang":"curl","source":"curl -X POST https://vigilant.trackjud.com.br/api/v1/consults/CONSULT_ID/reprocess \\\n  -H \"Authorization: Bearer vgl_your_api_key\""},{"label":"Python","lang":"Python","source":"import requests\n\nconsult_id = \"...\"\nr = requests.post(\n    f\"https://vigilant.trackjud.com.br/api/v1/consults/{consult_id}/reprocess\",\n    headers={\"Authorization\": \"Bearer vgl_your_api_key\"},\n)\nprint(r.json())"},{"label":"JavaScript","lang":"JavaScript","source":"const consultId = \"...\";\nconst r = await fetch(\n  `https://vigilant.trackjud.com.br/api/v1/consults/${consultId}/reprocess`,\n  {\n    method: \"POST\",\n    headers: { \"Authorization\": \"Bearer vgl_your_api_key\" }\n  }\n);\nconsole.log(await r.json());"}]}},"/api/v1/courts":{"get":{"callbacks":{},"description":"Returns all publicly visible court sources with their operational status. Use this to discover which courts can be searched and display available options to users. Courts with status `active` or `unavailable` can be included in consults. Courts with status `coming_soon` are under development and cannot be searched yet.","operationId":"listCourts","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CourtSourcesResponse"}}},"description":"Court sources list"},"401":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}},"description":"Missing or invalid API key"}},"security":[{"BearerAuth":[]}],"summary":"List available courts","tags":["Courts"],"x-codeSamples":[{"label":"cURL","lang":"curl","source":"curl https://vigilant.trackjud.com.br/api/v1/courts \\\n  -H \"Authorization: Bearer vgl_your_api_key\""},{"label":"Python","lang":"Python","source":"import requests\n\nr = requests.get(\n    \"https://vigilant.trackjud.com.br/api/v1/courts\",\n    headers={\"Authorization\": \"Bearer vgl_your_api_key\"},\n)\nprint(r.json())"},{"label":"JavaScript","lang":"JavaScript","source":"const r = await fetch(\"https://vigilant.trackjud.com.br/api/v1/courts\", {\n  headers: { \"Authorization\": \"Bearer vgl_your_api_key\" }\n});\nconsole.log(await r.json());"}]}}},"security":[],"servers":[{"url":"/","variables":{}}],"tags":[{"description":"How to authenticate, make your first call, and interpret the response. Includes a glossary of Brazilian legal terms used across the API.\n\n## 1. Account & API keys\n\nTo start using Vigilant, create a free account at [vigilant.trackjud.com.br](https://vigilant.trackjud.com.br). New accounts receive 5 free credits — enough to test the API across a few courts before purchasing.\n\nAfter signing in, navigate to **API Keys** in your dashboard and click **Create new key**. Give your key a descriptive name so you can identify it later. **The key is shown only once** — copy and store it in a secure location (password manager, secrets vault).\n\nUse the key in every request via the `Authorization` header:\n\n```\nAuthorization: Bearer vgl_your_api_key_here\n```\n\nYou can have multiple API keys per account. Revoke any key from the dashboard at any time — revocation is immediate. Rotating keys regularly is good practice. Your credit balance and full transaction history (purchases, charges, refunds) are always visible in the dashboard.\n\n## 2. First request\n\nThe most common operation is creating a **consult** — a search for a CPF across one or more Brazilian courts. Send a `POST /api/v1/consults` with the CPF and a list of court codes:\n\n```bash\ncurl -X POST https://vigilant.trackjud.com.br/api/v1/consults \\\n  -H \"Authorization: Bearer vgl_your_api_key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"document\": \"529.982.247-25\",\n    \"courts\": [\"TJSP\", \"TJMG\"]\n  }'\n```\n\nThe response status tells you what happened:\n\n- **`200 OK`** — Cache hit. Fresh data already exists for this CPF+courts   combination. The full result is returned immediately in the response body.\n- **`202 Accepted`** — Cache miss. Vigilant has triggered scraping in the background.   The response contains a `consult_id` you can use to poll for results via   `GET /api/v1/consults/{consult_id}`.\n- **`402 Payment Required`** — You do not have enough credits to run this consult.   Top up your balance in the dashboard.\n- **`422 Unprocessable Entity`** — The CPF format is invalid (failed the mod-11   check digit), or one of the court codes you sent is not in the registry.   Check the error response for details.\n\nWhen you receive a `202`, poll the consult until its status is `done`. A typical scraping run completes in under 60 seconds. Cached results from subsequent calls are served instantly without consuming additional credits.\n\n## 3. Response shape\n\nA successful consult returns a list of `courts`, each containing a list of `processes` (lawsuits found for that CPF in that court). Each process is a `ProcessRecord` with these key fields:\n\n- **`numero_processo_unico`** — CNJ standardized case number (always present, unique identifier)\n- **`classe`** — Case class (e.g., \"Procedimento Comum Cível\")\n- **`situacao`** — Current status in the court (e.g., \"Em andamento\", \"Arquivado\")\n- **`distribuido_em`** — Filing date\n- **`valor_causa`** — Case monetary value\n- **`instance`** — `\"1\"` for trial court, `\"2\"` for appeals court\n- **`partes`** — Array of parties involved (plaintiff, defendant, lawyers)\n- **`movimentos`** — Chronological history of case movements with dates\n- **`assuntos`** — Legal subject classification\n\nSome fields may be `null` when the source court does not expose that data. The CNJ number, however, is always populated — processes without a valid CNJ number are rejected during extraction. See the `ProcessRecordSchema` for the complete field list and types.\n\n## 4. Cache behavior and credits\n\nVigilant caches results to keep costs down and response times fast:\n\n- **Fresh cache (< 2 days old)**: returned instantly with `source: \"cache\"` and `stale: false`.\n- **Stale cache (>= 2 days old)**: returned instantly with `stale: true`, AND   a background refresh is triggered. Polling the consult later returns the fresh data.\n- **No cache**: triggers a fresh scrape (`202` with `consult_id` to poll).\n\nEach court searched costs **1 credit**. Using `force_refresh: true` bypasses the cache and costs **5 credits per court**. Credits never expire and are refunded automatically when a court fails after retries.\n\nRecords older than 14 days that have been superseded by newer data are cleaned up daily; the latest records per CPF+court combination are preserved indefinitely.\n\n## 5. Glossary\n\nVigilant's data uses Brazilian legal terminology. Here are the core terms:\n\n- **CPF** — *Cadastro de Pessoa Física*. Brazilian individual taxpayer ID (11 digits).   Comparable to a US SSN. Vigilant searches lawsuits by CPF.\n- **CNJ number** — Standardized unique process number defined by Brazil's   *Conselho Nacional de Justiça* (National Council of Justice). Format:   `NNNNNNN-DD.AAAA.J.TR.OOOO`. Every process has exactly one CNJ number.\n- **ESAJ** — *Sistema de Automação da Justiça*. Court software developed by   Softplan, used by several Brazilian state courts (TJSP, TJAC, TJCE, TJAL, TJAM).\n- **PJE** — *Processo Judicial Eletrônico*. CNJ's official court system, used by   TJMA, TJMG, TJPE, TJAP, TJCE, TRF1, and others.\n- **1st instance** — Trial court (first-level court).\n- **2nd instance** — Appeals court (second-level court). Vigilant returns both automatically.\n- **TJ** — *Tribunal de Justiça*. State-level court (e.g., TJSP = São Paulo state court).\n- **TRF** — *Tribunal Regional Federal*. Federal Regional Court.\n- **OAB** — *Ordem dos Advogados do Brasil*. Brazilian Bar Association. Lawyer   registration numbers appear in `partes` entries.\n- **`force_refresh`** — Optional flag in `POST /consults`. When `true`, bypasses   the cache and triggers a fresh scrape. Costs 5x the normal credit rate.\n- **Stale cache** — Cached data older than 2 days. Returned with `stale: true`   in the response, and a background refresh is triggered automatically.\n","name":"Getting Started"},{"description":"System health and readiness checks. No authentication required. Returns overall system status and basic dependency checks.","name":"Health"},{"description":"Court source registry. Lists all publicly visible Brazilian court endpoints with their operational status (active, unavailable, coming_soon). Use this to discover which courts can be included in consults.","name":"Courts"},{"description":"Consult lifecycle management. Create CPF searches across courts, poll for results, cancel pending consults, and reprocess failed searches. Each consult costs credits proportional to the number of courts searched.","name":"Consults"}],"x-tagGroups":[{"name":"Introduction","tags":["Getting Started"]},{"name":"Reference","tags":["Health","Courts","Consults"]}]}