> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitsearch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Structured search intent

> Describe names, work experience, skills, schools, location, demographics, and personalization for v3 Search.

The `intent` object describes who you want to find when your application already has structured criteria. Send it alone for a fully structured request, or alongside top-level [`query`](/api/search/search) when plain English provides useful context and specific fields need to be corrected or constrained.

When both are present, Orbit derives a base intent from `query` and overlays the caller-provided `intent`. At each supplied field, arrays, scalar values, and `null` replace the derived value; nested objects merge field by field.

```json theme={"dark"}
{
  "intent": {
    "experiences": [
      {
        "titleAnyOf": ["Machine Learning Engineer", "ML Engineer"],
        "organization": "OpenAI",
        "temporalScope": "current"
      }
    ],
    "semanticClauses": [
      { "text": "works on large language model inference" }
    ],
    "geo": {
      "place": "San Francisco Bay Area",
      "distance": "50 miles"
    }
  }
}
```

<Warning>
  Do not send `intent.version`. Orbit owns and applies the schema version internally.
</Warning>

## Top-level fields

| Field             | Type             | Description                                                         |
| ----------------- | ---------------- | ------------------------------------------------------------------- |
| `names`           | string\[]        | One or more person names.                                           |
| `experiences`     | object\[]        | Job title, organization, dates, and current/historical constraints. |
| `semanticClauses` | object\[]        | Free-form professional criteria that do not fit an exact field.     |
| `schools`         | object\[]        | School, dates, graduation year, or relationship.                    |
| `geo`             | object or `null` | Place, distance, and historical-location constraint.                |
| `demographics`    | object or `null` | Age, birth year, or gender constraints.                             |
| `personalization` | object or `null` | First-degree network or near-me constraints.                        |

Unknown and server-owned fields are rejected.

## Experience

```json theme={"dark"}
{
  "experiences": [
    {
      "title": "Founder",
      "titleAnyOf": ["Founder", "Co-founder"],
      "organization": "Example Co",
      "year": 2024,
      "startYear": 2020,
      "startYearLte": 2021,
      "endYear": 2025,
      "temporalScope": "current"
    }
  ]
}
```

`temporalScope` accepts `current`, `historical`, or `both`. Use either `title` or `titleAnyOf` when possible; sending both is allowed but usually redundant.

## Semantic clauses

```json theme={"dark"}
{
  "semanticClauses": [
    { "text": "built production recommendation systems" },
    { "anyOf": ["robotics", "autonomous vehicles"] }
  ]
}
```

Use `text` for one concept or `anyOf` for alternatives.

## Schools

```json theme={"dark"}
{
  "schools": [
    {
      "schoolAnyOf": ["Stanford University", "UC Berkeley"],
      "graduationYear": 2020,
      "temporalScope": "historical",
      "relation": "attended"
    }
  ]
}
```

School objects accept `school`, `schoolAnyOf`, `graduationYear`, `startYear`, `endYear`, `temporalScope`, and `relation`.

## Location and demographics

```json theme={"dark"}
{
  "geo": {
    "place": "New York City",
    "isHistorical": false,
    "distance": "25 miles"
  },
  "demographics": {
    "ageRange": { "min": 30, "max": 45 },
    "birthYearRange": { "min": 1980, "max": 1995 },
    "gender": "woman"
  }
}
```

Each range requires both `min` and `max`, and `min` must not exceed `max`.

## Personalization

```json theme={"dark"}
{
  "personalization": {
    "network": { "scope": "first_degree" },
    "nearMe": { "distance": "10 miles" }
  }
}
```

See [Start a search](/api/search/search) for the complete request contract.