Cases · Docs | Vaelor

A case holds one investigation: the goal, the starting material, any evidence files, and every run made against it. Cases are durable — runs continue in the background even if your client disconnects, and evidence is kept with its source so every claim in a report can be traced.

The typical flow:

Create a case with a goal and starting material.
Optionally attach files.
Start a run.
Poll events until the run finishes.
Retrieve the case or export the report.

Lawful use only

OSINT only searches publicly available sources. Don't use it to stalk, harass or dox anyone, or to process data you aren't permitted to process. See the Terms.

Create a case#

POSThttps://api.vaelor.chat/v1/osint/cases

Body

goalstringRequired

What you want to find out, 1–4,000 characters. Be specific about scope.

materialstringDefault ""

Starting material such as names, domains, usernames or pasted text, up to 50,000 characters.

curl https://api.vaelor.chat/v1/osint/cases \
  -H "Authorization: Bearer $VAELOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Map the public web footprint of the domain northwind-trading.example: hosting, related domains, and named staff.",
    "material": "northwind-trading.example\nFounded 2019, Rotterdam"
  }'

const { id } = await fetch('https://api.vaelor.chat/v1/osint/cases', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VAELOR_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    goal: 'Map the public web footprint of the domain northwind-trading.example.',
    material: 'northwind-trading.example\nFounded 2019, Rotterdam'
  })
}).then((response) => response.json())

case = requests.post(
    "https://api.vaelor.chat/v1/osint/cases",
    headers={"Authorization": f"Bearer {os.environ['VAELOR_API_KEY']}"},
    json={
        "goal": "Map the public web footprint of the domain northwind-trading.example.",
        "material": "northwind-trading.example\nFounded 2019, Rotterdam",
    },
).json()

Response201

JSON

{ "id": "a41f9c6e-2b8d-4e17-9f3a-6c0d5e8b2a91" }

Creating a case is free. Credits are charged when you start a run.

List cases#

GEThttps://api.vaelor.chat/v1/osint/cases

Returns your 100 most recent cases, the sources available to runs, and your monthly web-search quota.

Response

casesobject[]

Cases, newest first. Each has id, title, goal, material, createdAt and updatedAt.

capabilitiesobject[]

Each source a run can use: id, name, available and a note on coverage.

searchQuotaobject

Web searches used this month and the limit.

Response200

JSON

{
  "cases": [
    {
      "id": "a41f9c6e-2b8d-4e17-9f3a-6c0d5e8b2a91",
      "title": "Northwind Trading web footprint",
      "goal": "Map the public web footprint of the domain northwind-trading.example.",
      "material": "northwind-trading.example\nFounded 2019, Rotterdam",
      "createdAt": "2026-10-20T08:02:19.000Z",
      "updatedAt": "2026-10-20T08:14:51.000Z"
    }
  ],
  "capabilities": [
    { "id": "files", "name": "Documents and spreadsheets", "available": true, "note": "Local parsing; scanned PDFs may need clearer page images" },
    { "id": "images", "name": "Image clues and text", "available": true, "note": "Vision observations and embedded metadata; not reverse-image search" }
  ],
  "searchQuota": { "used": 312, "limit": 1000 }
}

Errors#

Status	When
`400`	The body isn't valid JSON, or `goal` is missing or too long.