Miner Concepts — kind, natures, tags and tiers - JUDIT

Public beta. The filter set may receive new options (especially tags for sentence-execution). Treat enums as open and ignore unknown values.

A Miner query is defined by a single filter object — the same schema is used by POST /requests/count (free) and POST /requests/create (charges credits). This page explains every field, its valid values and how they combine.

`kind` (required)

Defines which type of asset you’re discovering. It’s the first filter to choose because it constrains which other fields can appear.

Value	What it is	Allowed extra filters
`judgement-bond`	Judgement bonds — credits against the public administration arising from final judgments (Brazilian “precatórios”).	`budget_years`, `natures`
`sentence-execution`	Sentence executions — enforcement phase, where calculation may be approved or a bond may be issued.	`tags`

You cannot mix exclusive fields: tags with kind: judgement-bond or budget_years/natures with kind: sentence-execution fail with 400.

`natures` (only for `judgement-bond`)

Type of credit underlying the bond.

Value	Meaning
`alimentary`	Alimentary bond — wage credits, pensions, death indemnities, social-security benefits. Has payment priority.
`common`	Common bond — any other credit (tax, civil indemnity, expropriation, etc.).

{
  "kind": "judgement-bond",
  "natures": ["alimentary"]
}

Combine both to include everything: "natures": ["alimentary", "common"].

`budget_years` (only for `judgement-bond`)

Budget years in which the bond was registered. Use to filter specific vintages — typically the registration year is the calendar year following the final judgment.

{
  "kind": "judgement-bond",
  "budget_years": [2023, 2024]
}

`tags` (only for `sentence-execution`)

Signals detected by Judit’s base that indicate a maturation stage of the execution.

Value	What it indicates
`precatory_dispatched`	Bond already dispatched within the execution. The asset is about to become a `judgement-bond`.
`possible_precatory`	Textual signals suggesting a bond will be issued soon (rulings, dispatches, certifications).
`possible_approved_calculation`	Liquidation calculation seemingly approved — the step that usually precedes the bond.

{
  "kind": "sentence-execution",
  "tags": ["possible_precatory", "possible_approved_calculation"]
}

Multiple tags are treated as OR — any lawsuit with at least one of the tags is included.

Amount range

There are two mutually exclusive ways to filter by amount:

Mode 1 — Free limits (`amount_min` / `amount_max`)

{
  "kind": "judgement-bond",
  "amount_min": 50000,
  "amount_max": 500000
}

Field	Type	Rule
`amount_min`	number	Minimum amount, in BRL.
`amount_max`	number	Maximum amount, in BRL. Must be ≥ `amount_min`.

Use when you need a specific cut (e.g. “between R

50k and R

500k”).

Mode 2 — Pre-defined tier (`amount_tier`)

{
  "kind": "sentence-execution",
  "amount_tier": "250k-500k"
}

`amount_tier` value	Range in BRL
`0-100k`	up to R$ 100,000
`100k-250k`	R $100,000 to R$ 250,000
`250k-500k`	R $250,000 to R$ 500,000
`500k-750k`	R $500,000 to R$ 750,000
`750k-1.5M`	R $750,000 to R$ 1,500,000
`1.5M+`	above R$ 1,500,000

Use when you align with Judit’s commercial tiers — this is the recommended path because credit pricing is also tier-based.

Don’t combine the two modes. Sending amount_tier together with amount_min or amount_max fails with 400. Pick one.

`tribunals`

Array of numeric court IDs to include. Empty or absent = every court covered by Miner.

{
  "kind": "judgement-bond",
  "tribunals": [10, 18, 1]
}

To discover the IDs: call GET /tribunals or check the full table.

`responses_limit` (only on `/requests/create`)

Optional cap on the number of lawsuits materialized in a query. Has no effect on /requests/count — count always returns the real total.

{
  "kind": "sentence-execution",
  "tribunals": [10],
  "tags": ["possible_precatory"],
  "responses_limit": 500
}

Scenario	Behavior
`responses_limit` omitted	Materializes everything that matches (subject to plan limit).
`responses_limit: N` (N ≤ total)	Materializes exactly N lawsuits, ordered by an internal criterion. Cost proportional.
`responses_limit: N` (N > total)	Materializes everything available. Charged only for the real total.

Use it to control cost when count returned a high volume and you only want a sample.

Combination rules

Summary of everything that fails with 400:

Attempt	Why
`kind: judgement-bond` + `tags: [...]`	`tags` is exclusive to `sentence-execution`.
`kind: sentence-execution` + `budget_years: [...]`	`budget_years` is exclusive to `judgement-bond`.
`kind: sentence-execution` + `natures: [...]`	`natures` is exclusive to `judgement-bond`.
`amount_min: 100000` + `amount_tier: "250k-500k"`	Mutually exclusive amount modes.
`amount_min: 100000, amount_max: 50000`	`min` must be ≤ `max`.
Any unknown key (e.g. `state: "SP"`)	`RequestLawsuitsFiltersBody` is strict — unknown keys are rejected.

Full schema (quick reference)

{
  "kind": "judgement-bond" | "sentence-execution",                // required
  "tribunals": [10, 18],                                          // optional
  "amount_min": 50000,                                            // optional (cannot combine with amount_tier)
  "amount_max": 500000,                                           // optional (cannot combine with amount_tier)
  "amount_tier": "250k-500k",                                     // optional (cannot combine with min/max)
  "budget_years": [2023, 2024],                                   // judgement-bond only
  "natures": ["alimentary", "common"],                            // judgement-bond only
  "tags": ["possible_precatory"],                                 // sentence-execution only
  "responses_limit": 1000                                         // /requests/create only
}

Next steps

How billing works

cost calculation, price tiers and billing-error handling.

Court list

Full table of IDs accepted in the tribunals field.

Quickstart

Practical recipe with count → create → poll → paginate.

API Reference

Interactive spec to test every endpoint.

Getting Started

Concepts

API Reference · Miner

Miner Concepts — kind, natures, tags and tiers

`kind` (required)

`natures` (only for `judgement-bond`)

`budget_years` (only for `judgement-bond`)

`tags` (only for `sentence-execution`)

Amount range

Mode 1 — Free limits (`amount_min` / `amount_max`)

Mode 2 — Pre-defined tier (`amount_tier`)

`tribunals`

`responses_limit` (only on `/requests/create`)

Combination rules

Full schema (quick reference)

Next steps

How billing works

Court list

Quickstart

API Reference

​kind (required)

​natures (only for judgement-bond)

​budget_years (only for judgement-bond)

​tags (only for sentence-execution)

​Amount range

​Mode 1 — Free limits (amount_min / amount_max)

​Mode 2 — Pre-defined tier (amount_tier)

​tribunals

​responses_limit (only on /requests/create)

​Combination rules

​Full schema (quick reference)

​Next steps

How billing works

Court list

Quickstart

API Reference

`kind` (required)

`natures` (only for `judgement-bond`)

`budget_years` (only for `judgement-bond`)

`tags` (only for `sentence-execution`)

Amount range

Mode 1 — Free limits (`amount_min` / `amount_max`)

Mode 2 — Pre-defined tier (`amount_tier`)

`tribunals`

`responses_limit` (only on `/requests/create`)

Combination rules

Full schema (quick reference)

Next steps