# Intrace Intelligence API

> Documentation and API reference for the Intrace Intelligence API

This document contains the full content of all documentation pages for AI consumption.

---

## Authentication

**URL:** https://docs.ie.intrace.ai/docs/authentication
**Description:** How to authenticate requests to the Intelligence API

The production API is available at `https://api.ie.intrace.ai/`. Authenticated endpoints accept a provisioned API key in either header form.

Primary form:

```http
X-API-Key: intrace_live_...
```

Bearer form:

```http
Authorization: Bearer intrace_live_...
```

The capability endpoints require authentication. `/healthz` and `/readyz` are operational endpoints and are not authenticated in the OpenAPI contract.

## Error responses

Missing or invalid keys return the standard error envelope:

```json
{
  "error": {
    "code": "missing_api_key",
    "message": "An API key is required",
    "retryable": false
  }
}
```

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "The supplied API key is invalid",
    "retryable": false
  }
}
```

---

## Capabilities

**URL:** https://docs.ie.intrace.ai/docs/capabilities
**Description:** What each current Intelligence API capability does

## Web search

Use web search to find public web, news, supported public social/profile mentions, public documents, and adverse-media references for a person, organization, or keyword. This capability is intended for adverse-media review, public-context discovery, and triage workflows where an investigator needs normalized hits with enough context to decide what to review next.

Requests can include expanded person-subject context such as date of birth, place of birth, email address, approximate age, mobile phone number, driver's license state, body type/build, military status, ethnicity, employer, employment dates, department, role, location, employment status, and subject-owned social media URLs. These fields follow the normal API naming convention shown in the generated reference.

The API uses these fields according to their reliability. Name, aliases, regions, employer, employment location, place of birth, role, and department may narrow generated search queries. Exact subject social media URLs are routed through the same social-context retrieval path as `socialAccounts`. Email, phone, date of birth, employment dates, license state, employment status, gender, ethnicity, body type/build, and military status are used for corroboration or exclusion context, not as standalone reasons to include a result.

Search is identity-led, not adverse-term-gated. The service generates capped query categories similar to the platform search flow: pure identity, news/media, social/professional, profile/contact, public document, and adverse-media. `adverseTerms` are optional caller additions/boosts; when omitted, the API still uses a built-in adverse/legal/regulatory term pack and still keeps subject-relevant non-adverse results.

Requests can also include exact social account hints in top-level `socialAccounts` using a supported platform plus username or profile URL. The API uses those hints to retrieve available profile and recent-activity context from the existing social scrapers and returns that context as normalized social web hits alongside general web/news search results.

Results are returned as normalized web-hit items with `confidenceCategory`, matched inputs, summary text, metadata, display domain, source type, content type, publication time when available, and `resultUrl` for the full source page URL. Safe metadata can include the generated `queryCategory` that found the result. Web/media search intentionally exposes the source URL so investigators can review the underlying page.

## PII expansion

Use PII expansion to expand supplied identifier seeds: emails, phones, and usernames. This capability is intentionally identifier-only; address/domain seeds, standalone name/DOB/region person searches, reverse-phone identity enrichment, broad person enrichment, and social-profile discovery are excluded.

Results include `identity_candidate` items only. Each returned item includes `confidenceCategory`, match rationale, matched inputs, normalized identifier attributes, and safe metadata so consumers can rank and review candidate links. Breach-derived identity candidates may preserve safe field-level context such as `exposedFields`, `credentialExposure`, and `credentialTypes`; breach source names/dates, credential values, hashes, salts, tokens, and raw connector payloads are not returned.

PII expansion dedupes exact identifier matches algorithmically first. AI semantic dedupe and validation then merge compatible identity variants or exclude irrelevant/junk identifiers. The AI step can only choose merge/keep-separate or include/exclude and never changes returned values.

## Social Profile Analysis

Use Social Profile Analysis when the caller already knows the social profile URL(s) to analyze. The base `match` layer retrieves records from those profiles and returns posts, comments, videos, profile fields, and other evidence that match analyst criteria or a custom prompt.

Optional `behavioral_analysis` runs on top of the matched records. It can summarize behavior over time, identify escalation or repeated target mentions, assess risk signals when a target context is provided, and explain limits. This capability is not a person-resolution or candidate-profile discovery workflow.

## Output guarantees

Responses are designed for downstream analysis, triage, and workflow integration. They are normalized API results, not raw-source evidence exports. Confidence is returned as `likely` or `uncertain` on each normalized result item.

---

## Introduction

**URL:** https://docs.ie.intrace.ai/docs
**Description:** Guide to the Intrace Intelligence API

The Intrace Intelligence API is an API-first OSINT service for customer intelligence workflows. It exposes three capabilities:

- **Web search** for normalized web, news, and supported public social/adverse-media hits.
- **PII expansion** for expanding email, phone, and username identifiers into identifier-only identity candidates.
- **Social Profile Analysis** for analyzing known social profile URLs. The base Match layer returns matching records from those profiles; optional Behavioral Analysis explains patterns, escalation, risk signals, and target-context relevance.

All capability responses are normalized, deduplicated, and shaped for API consumption. Web/adverse-media results include `resultUrl` so investigators can review the underlying page. PII expansion focuses on normalized identifier candidates. Social Profile Analysis is evidence-first and does not discover or score candidate profiles.

## Base URL

The production Intelligence API endpoint is:

```http
https://api.ie.intrace.ai/
```

Capability endpoints are served under `/v1`:

```http
POST https://api.ie.intrace.ai/v1/web-search
POST https://api.ie.intrace.ai/v1/pii-expansion
POST https://api.ie.intrace.ai/v1/social-profile-analysis
```

Operational health endpoints are exposed at `https://api.ie.intrace.ai/healthz` and `https://api.ie.intrace.ai/readyz`.

## Access patterns

Each capability supports the same three patterns:

1. **Inline REST**: `POST /v1/<capability>` with `responseMode: "sync"`.
2. **Async jobs**: `POST /v1/<capability>` with `responseMode: "async"`, then poll the returned `resultUrl`.
3. **Server-sent events**: `POST /v1/<capability>/stream` for progress and result events.

See the API Reference for exact request and response schemas. The reference is generated from the implemented API contract.

---

## Jobs and pagination

**URL:** https://docs.ie.intrace.ai/docs/jobs
**Description:** How async capability jobs work

Every capability creates a persisted job. Inline calls return a final result only if the job completes before the inline timeout; otherwise the API returns a job envelope with `202 Accepted`.

All `POST` and `POST /stream` responses include:

```http
X-Job-Id: job_...
```

A job envelope contains `jobId`, `capability`, `status`, timestamps, progress, summary, result, error, warnings, `resultUrl`, and `streamUrl`.

## Lifecycle

Jobs move through these statuses:

- `queued`
- `running`
- `completed`
- `failed`
- `expired`

## Result lookup

Use the capability-specific job endpoint returned in `resultUrl`:

```http
GET /v1/web-search/jobs/{job_id}?limit=25&cursor=...
GET /v1/pii-expansion/jobs/{job_id}?limit=25&cursor=...
GET /v1/social-profile-analysis/jobs/{job_id}?limit=25&cursor=...
```

When complete, `result` contains one page of normalized items. Preserve `nextCursor` exactly as returned; it is opaque.

---

## Streaming

**URL:** https://docs.ie.intrace.ai/docs/streaming
**Description:** Server-sent event support for live job progress

Each capability exposes a streaming creation endpoint:

```http
POST /v1/web-search/stream
POST /v1/pii-expansion/stream
POST /v1/social-profile-analysis/stream
```

The response content type is `text/event-stream`. The API emits typed server-sent events for job creation, progress, items, partial results, final results, errors, and heartbeat comments.

Use the `X-Job-Id` response header to reconnect to the job stream URL:

```http
GET /v1/social-profile-analysis/jobs/{job_id}/stream
Last-Event-ID: 2
```

Reconnect stream endpoints are operationally supported but intentionally hidden from the generated public OpenAPI schema.

---

## Service liveness check

**URL:** https://docs.ie.intrace.ai/docs/api-reference/healthz

<div className="not-prose my-6 rounded-lg border border-border bg-muted/40 p-4">
  <div className="flex flex-wrap items-center gap-3">
    <span className="rounded bg-[var(--accent-muted)] px-2 py-1 text-sm font-semibold text-[var(--accent)]">GET</span>
    <code className="text-sm">{`/healthz`}</code>
  </div>
  <p className="mt-3 text-sm text-muted-foreground">{`No API key is required.`}</p>
</div>

## Request

This endpoint does not require a request body.

## Responses

### `200`

Successful Response

| Field | Type | Required | Description |
|---|---|---:|---|
| `environment` | string | Yes | Environment |
| `service` | string | Yes | Service |
| `status` | string | No | Status Default: `"ok"` |
| `version` | string | Yes | Version |

## OpenAPI

Download the full OpenAPI contract from [`/openapi.yaml`](/openapi.yaml).

---

## Read a PII expansion job

**URL:** https://docs.ie.intrace.ai/docs/api-reference/pii-expansion-job
**Description:** Read the persisted job envelope for one PII-expansion run. When the job has completed, the `result` field contains a paginated page of normalized item

<div className="not-prose my-6 rounded-lg border border-border bg-muted/40 p-4">
  <div className="flex flex-wrap items-center gap-3">
    <span className="rounded bg-[var(--accent-muted)] px-2 py-1 text-sm font-semibold text-[var(--accent)]">GET</span>
    <code className="text-sm">{`/v1/pii-expansion/jobs/{job_id}`}</code>
  </div>
  <p className="mt-3 text-sm text-muted-foreground">{`Requires X-API-Key or Authorization: Bearer with a provisioned API key.`}</p>
</div>

Read the persisted job envelope for one PII-expansion run. When the job has completed, the `result` field contains a paginated page of normalized items controlled by the `limit` and `cursor` query parameters.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---:|---|
| `job_id` | path | string | Yes | — |
| `limit` | query | integer | No | — |
| `cursor` | query | string or null | No | — |

## Responses

### `200`

Persisted job state with an optional paginated result page.

| Field | Type | Required | Description |
|---|---|---:|---|
| `capability` | `Capability` | Yes | — |
| `completedAt` | string or null | No | Completedat |
| `error` | `ApiError` or null | No | — |
| `expiresAt` | string or null | No | Expiresat |
| `jobId` | string | Yes | Jobid |
| `progress` | `JobProgress` or null | No | — |
| `result` | `PiiExpansionResult` or null | No | — |
| `resultUrl` | string or null | No | Resulturl |
| `startedAt` | string or null | No | Startedat |
| `status` | `JobStatus` | Yes | — |
| `streamUrl` | string or null | No | Streamurl |
| `submittedAt` | string | Yes | Submittedat |
| `summary` | `JobSummary` or null | No | — |
| `warnings` | array&lt;`ApiWarning`&gt; | No | Warnings |

### `422`

Validation Error

| Field | Type | Required | Description |
|---|---|---:|---|
| `detail` | array&lt;`ValidationError`&gt; | No | Detail |

## OpenAPI

Download the full OpenAPI contract from [`/openapi.yaml`](/openapi.yaml).

---

## Run PII expansion

**URL:** https://docs.ie.intrace.ai/docs/api-reference/pii-expansion-run
**Description:** Create a PII-expansion job and wait for an inline result when `responseMode` is `sync`. If the job does not finish before the inline timeout, or when 

<div className="not-prose my-6 rounded-lg border border-border bg-muted/40 p-4">
  <div className="flex flex-wrap items-center gap-3">
    <span className="rounded bg-[var(--accent-muted)] px-2 py-1 text-sm font-semibold text-[var(--accent)]">POST</span>
    <code className="text-sm">{`/v1/pii-expansion`}</code>
  </div>
  <p className="mt-3 text-sm text-muted-foreground">{`Requires X-API-Key or Authorization: Bearer with a provisioned API key.`}</p>
</div>

Create a PII-expansion job and wait for an inline result when `responseMode` is `sync`. If the job does not finish before the inline timeout, or when `responseMode` is `async`, the API returns a persisted job envelope. Every response includes `X-Job-Id` for later lookup.

## Request body

| Field | Type | Required | Description |
|---|---|---:|---|
| `depth` | `ExpansionDepth` | No | Default: `"standard"` |
| `maxCandidates` | integer | No | Maxcandidates Default: `10` |
| `responseMode` | `ResponseMode` | No | Default: `"sync"` |
| `seeds` | `PiiExpansionSeeds` | No | — |
| `subject` | `PiiExpansionSubject` | Yes | — |

## Request examples

### Seeded identity expansion

Expand from one or more supported email, phone, or username seeds.

```json
{
  "depth": "standard",
  "maxCandidates": 10,
  "responseMode": "sync",
  "seeds": {
    "emails": [
      "john.smith@example.com"
    ],
    "phones": [
      "+15555550100"
    ],
    "usernames": [
      "johnsmith"
    ]
  },
  "subject": {
    "name": "John Smith"
  }
}
```

## Responses

### `200`

Normalized identity and related social-candidate results when completed inline, otherwise a job envelope.

Schema: `PiiExpansionResult` or `JobEnvelope_PiiExpansionResult_`

### `422`

Validation Error

| Field | Type | Required | Description |
|---|---|---:|---|
| `detail` | array&lt;`ValidationError`&gt; | No | Detail |

## OpenAPI

Download the full OpenAPI contract from [`/openapi.yaml`](/openapi.yaml).

---

## Create and stream a PII expansion job

**URL:** https://docs.ie.intrace.ai/docs/api-reference/pii-expansion-stream
**Description:** Create a persisted PII-expansion job and immediately stream typed server-sent events until completion. Use the `X-Job-Id` response header to reconnect

<div className="not-prose my-6 rounded-lg border border-border bg-muted/40 p-4">
  <div className="flex flex-wrap items-center gap-3">
    <span className="rounded bg-[var(--accent-muted)] px-2 py-1 text-sm font-semibold text-[var(--accent)]">POST</span>
    <code className="text-sm">{`/v1/pii-expansion/stream`}</code>
  </div>
  <p className="mt-3 text-sm text-muted-foreground">{`Requires X-API-Key or Authorization: Bearer with a provisioned API key.`}</p>
</div>

Create a persisted PII-expansion job and immediately stream typed server-sent events until completion. Use the `X-Job-Id` response header to reconnect at `GET /v1/pii-expansion/jobs/{job_id}/stream` with `Last-Event-ID`.

## Request body

| Field | Type | Required | Description |
|---|---|---:|---|
| `depth` | `ExpansionDepth` | No | Default: `"standard"` |
| `maxCandidates` | integer | No | Maxcandidates Default: `10` |
| `seeds` | `PiiExpansionSeeds` | No | — |
| `subject` | `PiiExpansionSubject` | Yes | — |

## Request examples

### Seeded identity expansion

Expand from one or more supported email, phone, or username seeds.

```json
{
  "depth": "standard",
  "maxCandidates": 10,
  "seeds": {
    "emails": [
      "john.smith@example.com"
    ],
    "phones": [
      "+15555550100"
    ],
    "usernames": [
      "johnsmith"
    ]
  },
  "subject": {
    "name": "John Smith"
  }
}
```

## Responses

### `200`

Successful Response

### `422`

Validation Error

| Field | Type | Required | Description |
|---|---|---:|---|
| `detail` | array&lt;`ValidationError`&gt; | No | Detail |

## OpenAPI

Download the full OpenAPI contract from [`/openapi.yaml`](/openapi.yaml).

---

## Service readiness check

**URL:** https://docs.ie.intrace.ai/docs/api-reference/readyz

<div className="not-prose my-6 rounded-lg border border-border bg-muted/40 p-4">
  <div className="flex flex-wrap items-center gap-3">
    <span className="rounded bg-[var(--accent-muted)] px-2 py-1 text-sm font-semibold text-[var(--accent)]">GET</span>
    <code className="text-sm">{`/readyz`}</code>
  </div>
  <p className="mt-3 text-sm text-muted-foreground">{`No API key is required.`}</p>
</div>

## Request

This endpoint does not require a request body.

## Responses

### `200`

Successful Response

| Field | Type | Required | Description |
|---|---|---:|---|
| `environment` | string | Yes | Environment |
| `service` | string | Yes | Service |
| `status` | string | No | Status Default: `"ok"` |
| `version` | string | Yes | Version |

## OpenAPI

Download the full OpenAPI contract from [`/openapi.yaml`](/openapi.yaml).

---

## Read a Social Profile Analysis job

**URL:** https://docs.ie.intrace.ai/docs/api-reference/social-profile-analysis-job
**Description:** Read the persisted job envelope for one Social Profile Analysis run. When complete, `result.match.matchedRecords` and `result.items` contain the reque

<div className="not-prose my-6 rounded-lg border border-border bg-muted/40 p-4">
  <div className="flex flex-wrap items-center gap-3">
    <span className="rounded bg-[var(--accent-muted)] px-2 py-1 text-sm font-semibold text-[var(--accent)]">GET</span>
    <code className="text-sm">{`/v1/social-profile-analysis/jobs/{job_id}`}</code>
  </div>
  <p className="mt-3 text-sm text-muted-foreground">{`Requires X-API-Key or Authorization: Bearer with a provisioned API key.`}</p>
</div>

Read the persisted job envelope for one Social Profile Analysis run. When complete, `result.match.matchedRecords` and `result.items` contain the requested matched-record page.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---:|---|
| `job_id` | path | string | Yes | — |
| `limit` | query | integer | No | — |
| `cursor` | query | string or null | No | — |

## Responses

### `200`

Persisted job state with an optional paginated Social Profile Analysis result.

| Field | Type | Required | Description |
|---|---|---:|---|
| `capability` | `Capability` | Yes | — |
| `completedAt` | string or null | No | Completedat |
| `error` | `ApiError` or null | No | — |
| `expiresAt` | string or null | No | Expiresat |
| `jobId` | string | Yes | Jobid |
| `progress` | `JobProgress` or null | No | — |
| `result` | `SocialProfileAnalysisResult` or null | No | — |
| `resultUrl` | string or null | No | Resulturl |
| `startedAt` | string or null | No | Startedat |
| `status` | `JobStatus` | Yes | — |
| `streamUrl` | string or null | No | Streamurl |
| `submittedAt` | string | Yes | Submittedat |
| `summary` | `JobSummary` or null | No | — |
| `warnings` | array&lt;`ApiWarning`&gt; | No | Warnings |

### `422`

Validation Error

| Field | Type | Required | Description |
|---|---|---:|---|
| `detail` | array&lt;`ValidationError`&gt; | No | Detail |

## OpenAPI

Download the full OpenAPI contract from [`/openapi.yaml`](/openapi.yaml).

---

## Run Social Profile Analysis

**URL:** https://docs.ie.intrace.ai/docs/api-reference/social-profile-analysis-run
**Description:** Create a Social Profile Analysis job for known social profile URLs. The base Match layer returns matched records; optional Behavioral Analysis adds in

<div className="not-prose my-6 rounded-lg border border-border bg-muted/40 p-4">
  <div className="flex flex-wrap items-center gap-3">
    <span className="rounded bg-[var(--accent-muted)] px-2 py-1 text-sm font-semibold text-[var(--accent)]">POST</span>
    <code className="text-sm">{`/v1/social-profile-analysis`}</code>
  </div>
  <p className="mt-3 text-sm text-muted-foreground">{`Requires X-API-Key or Authorization: Bearer with a provisioned API key.`}</p>
</div>

Create a Social Profile Analysis job for known social profile URLs. The base Match layer returns matched records; optional Behavioral Analysis adds interpretation over those matched records. When `responseMode` is `sync`, the API waits for an inline result until the configured timeout. Every response includes `X-Job-Id`.

## Request body

| Field | Type | Required | Description |
|---|---|---:|---|
| `analysisTypes` | array&lt;`AnalysisType`&gt; | No | Analysistypes Default: `["match"]` |
| `behavioralAnalysis` | `BehavioralAnalysisConfig` or null | No | — |
| `match` | `SocialProfileAnalysisMatchConfig` | Yes | — |
| `responseMode` | `ResponseMode` | No | Default: `"sync"` |
| `subject` | `SocialProfileAnalysisSubject` | Yes | — |

## Request examples

### Known-profile match analysis

Analyze known social profile URLs against natural-language match criteria.

```json
{
  "analysisTypes": [
    "match"
  ],
  "match": {
    "criteria": [
      "fraud",
      "theft",
      "crime"
    ],
    "maxRecords": 25
  },
  "responseMode": "sync",
  "subject": {
    "name": "John Smith",
    "socialMediaUrls": [
      "https://x.com/johnsmith"
    ]
  }
}
```

## Responses

### `200`

Matched social records and optional behavioral analysis when completed inline, otherwise a job envelope.

Schema: `SocialProfileAnalysisResult` or `JobEnvelope_SocialProfileAnalysisResult_`

### `422`

Validation Error

| Field | Type | Required | Description |
|---|---|---:|---|
| `detail` | array&lt;`ValidationError`&gt; | No | Detail |

## OpenAPI

Download the full OpenAPI contract from [`/openapi.yaml`](/openapi.yaml).

---

## Create and stream a Social Profile Analysis job

**URL:** https://docs.ie.intrace.ai/docs/api-reference/social-profile-analysis-stream
**Description:** Create a persisted Social Profile Analysis job and stream typed server-sent events until completion. Use the `X-Job-Id` response header to reconnect a

<div className="not-prose my-6 rounded-lg border border-border bg-muted/40 p-4">
  <div className="flex flex-wrap items-center gap-3">
    <span className="rounded bg-[var(--accent-muted)] px-2 py-1 text-sm font-semibold text-[var(--accent)]">POST</span>
    <code className="text-sm">{`/v1/social-profile-analysis/stream`}</code>
  </div>
  <p className="mt-3 text-sm text-muted-foreground">{`Requires X-API-Key or Authorization: Bearer with a provisioned API key.`}</p>
</div>

Create a persisted Social Profile Analysis job and stream typed server-sent events until completion. Use the `X-Job-Id` response header to reconnect at `GET /v1/social-profile-analysis/jobs/{job_id}/stream`.

## Request body

| Field | Type | Required | Description |
|---|---|---:|---|
| `analysisTypes` | array&lt;`AnalysisType`&gt; | No | Analysistypes Default: `["match"]` |
| `behavioralAnalysis` | `BehavioralAnalysisConfig` or null | No | — |
| `match` | `SocialProfileAnalysisMatchConfig` | Yes | — |
| `subject` | `SocialProfileAnalysisSubject` | Yes | — |

## Request examples

### Known-profile match analysis

Analyze known social profile URLs against natural-language match criteria.

```json
{
  "analysisTypes": [
    "match"
  ],
  "match": {
    "criteria": [
      "fraud",
      "theft",
      "crime"
    ],
    "maxRecords": 25
  },
  "subject": {
    "name": "John Smith",
    "socialMediaUrls": [
      "https://x.com/johnsmith"
    ]
  }
}
```

## Responses

### `200`

Successful Response

### `422`

Validation Error

| Field | Type | Required | Description |
|---|---|---:|---|
| `detail` | array&lt;`ValidationError`&gt; | No | Detail |

## OpenAPI

Download the full OpenAPI contract from [`/openapi.yaml`](/openapi.yaml).

---

## Read a web/media search job

**URL:** https://docs.ie.intrace.ai/docs/api-reference/web-search-job
**Description:** Read the persisted job envelope for one web-search run. When the job has completed, the `result` field contains a paginated page of normalized items c

<div className="not-prose my-6 rounded-lg border border-border bg-muted/40 p-4">
  <div className="flex flex-wrap items-center gap-3">
    <span className="rounded bg-[var(--accent-muted)] px-2 py-1 text-sm font-semibold text-[var(--accent)]">GET</span>
    <code className="text-sm">{`/v1/web-search/jobs/{job_id}`}</code>
  </div>
  <p className="mt-3 text-sm text-muted-foreground">{`Requires X-API-Key or Authorization: Bearer with a provisioned API key.`}</p>
</div>

Read the persisted job envelope for one web-search run. When the job has completed, the `result` field contains a paginated page of normalized items controlled by the `limit` and `cursor` query parameters.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---:|---|
| `job_id` | path | string | Yes | — |
| `limit` | query | integer | No | — |
| `cursor` | query | string or null | No | — |

## Responses

### `200`

Persisted job state with an optional paginated result page.

| Field | Type | Required | Description |
|---|---|---:|---|
| `capability` | `Capability` | Yes | — |
| `completedAt` | string or null | No | Completedat |
| `error` | `ApiError` or null | No | — |
| `expiresAt` | string or null | No | Expiresat |
| `jobId` | string | Yes | Jobid |
| `progress` | `JobProgress` or null | No | — |
| `result` | `WebSearchResult` or null | No | — |
| `resultUrl` | string or null | No | Resulturl |
| `startedAt` | string or null | No | Startedat |
| `status` | `JobStatus` | Yes | — |
| `streamUrl` | string or null | No | Streamurl |
| `submittedAt` | string | Yes | Submittedat |
| `summary` | `JobSummary` or null | No | — |
| `warnings` | array&lt;`ApiWarning`&gt; | No | Warnings |

### `422`

Validation Error

| Field | Type | Required | Description |
|---|---|---:|---|
| `detail` | array&lt;`ValidationError`&gt; | No | Detail |

## OpenAPI

Download the full OpenAPI contract from [`/openapi.yaml`](/openapi.yaml).

---

## Run web/media search

**URL:** https://docs.ie.intrace.ai/docs/api-reference/web-search-run
**Description:** Create a web-search job and wait for an inline result when `responseMode` is `sync`. If the job does not finish before the inline timeout, or when `re

<div className="not-prose my-6 rounded-lg border border-border bg-muted/40 p-4">
  <div className="flex flex-wrap items-center gap-3">
    <span className="rounded bg-[var(--accent-muted)] px-2 py-1 text-sm font-semibold text-[var(--accent)]">POST</span>
    <code className="text-sm">{`/v1/web-search`}</code>
  </div>
  <p className="mt-3 text-sm text-muted-foreground">{`Requires X-API-Key or Authorization: Bearer with a provisioned API key.`}</p>
</div>

Create a web-search job and wait for an inline result when `responseMode` is `sync`. If the job does not finish before the inline timeout, or when `responseMode` is `async`, the API returns a persisted job envelope. Every response includes `X-Job-Id` for later lookup.

## Request body

| Field | Type | Required | Description |
|---|---|---:|---|
| `adverseTerms` | array&lt;string&gt; | No | Optional adverse-media terms to search alongside the subject. The service also uses a built-in adverse/legal/regulatory term pack. |
| `dateRange` | `WebSearchDateRange` or null | No | — |
| `maxResults` | integer | No | Maxresults Default: `50` |
| `platformFilters` | array&lt;`WebPlatform`&gt; | No | Platformfilters Default: `["web", "news"]` |
| `responseMode` | `ResponseMode` | No | Default: `"sync"` |
| `seedUrls` | array&lt;string&gt; | No | Seedurls |
| `socialAccounts` | array&lt;`WebSearchSocialAccount`&gt; | No | Socialaccounts |
| `subject` | `WebSearchSubject` | Yes | — |

## Request examples

### Person web/media search

Search public web/media with built-in adverse discovery for a person subject.

```json
{
  "adverseTerms": [
    "fraud",
    "theft",
    "crime"
  ],
  "responseMode": "sync",
  "subject": {
    "name": "John Smith",
    "type": "person"
  }
}
```

## Responses

### `200`

Normalized search hits when completed inline, otherwise a job envelope.

Schema: `WebSearchResult` or `JobEnvelope_WebSearchResult_`

### `422`

Validation Error

| Field | Type | Required | Description |
|---|---|---:|---|
| `detail` | array&lt;`ValidationError`&gt; | No | Detail |

## OpenAPI

Download the full OpenAPI contract from [`/openapi.yaml`](/openapi.yaml).

---

## Create and stream a web/media search job

**URL:** https://docs.ie.intrace.ai/docs/api-reference/web-search-stream
**Description:** Create a persisted web-search job and immediately stream typed server-sent events until completion. Use the `X-Job-Id` response header to reconnect at

<div className="not-prose my-6 rounded-lg border border-border bg-muted/40 p-4">
  <div className="flex flex-wrap items-center gap-3">
    <span className="rounded bg-[var(--accent-muted)] px-2 py-1 text-sm font-semibold text-[var(--accent)]">POST</span>
    <code className="text-sm">{`/v1/web-search/stream`}</code>
  </div>
  <p className="mt-3 text-sm text-muted-foreground">{`Requires X-API-Key or Authorization: Bearer with a provisioned API key.`}</p>
</div>

Create a persisted web-search job and immediately stream typed server-sent events until completion. Use the `X-Job-Id` response header to reconnect at `GET /v1/web-search/jobs/{job_id}/stream` with `Last-Event-ID`.

## Request body

| Field | Type | Required | Description |
|---|---|---:|---|
| `adverseTerms` | array&lt;string&gt; | No | Optional adverse-media terms to search alongside the subject. The service also uses a built-in adverse/legal/regulatory term pack. |
| `dateRange` | `WebSearchDateRange` or null | No | — |
| `maxResults` | integer | No | Maxresults Default: `50` |
| `platformFilters` | array&lt;`WebPlatform`&gt; | No | Platformfilters Default: `["web", "news"]` |
| `seedUrls` | array&lt;string&gt; | No | Seedurls |
| `socialAccounts` | array&lt;`WebSearchSocialAccount`&gt; | No | Socialaccounts |
| `subject` | `WebSearchSubject` | Yes | — |

## Request examples

### Person web/media search

Search public web/media with built-in adverse discovery for a person subject.

```json
{
  "adverseTerms": [
    "fraud",
    "theft",
    "crime"
  ],
  "subject": {
    "name": "John Smith",
    "type": "person"
  }
}
```

## Responses

### `200`

Successful Response

### `422`

Validation Error

| Field | Type | Required | Description |
|---|---|---:|---|
| `detail` | array&lt;`ValidationError`&gt; | No | Detail |

## OpenAPI

Download the full OpenAPI contract from [`/openapi.yaml`](/openapi.yaml).

---

## Configuration

**URL:** https://docs.ie.intrace.ai/docs/deployment/configuration
**Description:** Runtime configuration notes for customer deployments

The API is deployed as a containerized service. Configure accepted API keys, optional Redis/Valkey-backed shared state, connector runtime settings, social-match evaluator settings, and required PII expansion AI settings through environment variables.

Common variables:

- `INTELLIGENCE_API_API_KEYS` or `INTELLIGENCE_API_KEYS_JSON`: API keys accepted by the service.
- `INTELLIGENCE_API_REDIS_URL`: optional Redis/Valkey URL for shared job lookup and rate limiting.
- `INTELLIGENCE_API_JOB_STORE_BACKEND`: `memory` or `redis`.
- `INTELLIGENCE_API_RATE_LIMIT_BACKEND`: `memory` or `redis`.
- `INTELLIGENCE_API_SOCIAL_MATCH_EVALUATOR_BASE_URL`: optional external evaluator base URL.
- `INTELLIGENCE_API_SOCIAL_MATCH_EVALUATOR_API_KEY`: optional external evaluator API key.
- `INTELLIGENCE_API_SOCIAL_MATCH_EVALUATOR_MODEL`: optional evaluator model name.
- `INTELLIGENCE_API_PII_EXPANSION_AI_API_KEY` or `OPENROUTER_API_KEY`: required for PII expansion semantic dedupe and validation.
- `INTELLIGENCE_API_PII_EXPANSION_AI_MODEL`: PII expansion AI model name.
- `INTELLIGENCE_API_PII_EXPANSION_AI_TIMEOUT_SECONDS`: PII expansion AI timeout.

For multi-replica deployments, use Redis/Valkey-backed job storage and rate limiting so job lookup and request budgets are shared across instances.

---

## Errors

**URL:** https://docs.ie.intrace.ai/docs/reference/errors
**Description:** Standard error model and common status codes

Errors use a shared envelope:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed",
    "retryable": false
  }
}
```

Common status codes:

| Status | Meaning |
|---|---|
| `401` | Missing or invalid API key. |
| `404` | Job not found for this capability or API key. |
| `410` | Job existed but expired. |
| `422` | Request body or query parameters failed validation. |
| `429` | API key exceeded its request budget. |
| `500` | Unexpected server-side failure. |
| `503` | API key authentication is not configured. |

The generated API Reference contains the exact response schemas emitted by the service.

---

## Rate limits

**URL:** https://docs.ie.intrace.ai/docs/reference/rate-limits
**Description:** Request budget behavior

Authenticated responses include request-budget headers when rate limiting is configured:

```http
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1780080000
```

When a key exceeds its budget, the API returns `429 Too Many Requests` with the standard error envelope and `retryable: true`.

Avoid aggressive polling. Prefer SSE streaming for user-interface workflows that need live progress.

---

## Links

- [Support](mailto:team@intrace.com)