# Data Models

# Data Models

Canonical shapes for Platform API request and response bodies.

## `ApiKeyHeader`

_Non-object schema, see OpenAPI spec for details._

## `ArtifactSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string (uuid)` | yes |  |
| `business_id` | `unknown` | yes |  |
| `created_by` | `unknown` | yes |  |
| `artifact_type` | `string` | yes |  |
| `title` | `string` | yes |  |
| `description` | `string | null` | yes |  |
| `status` | `enum("draft" | "saved" | "archived")` | yes |  |
| `content_markdown` | `string | null` | yes |  |
| `content_json` | `object | null` | yes |  |
| `current_version` | `integer` | yes |  |
| `source_table` | `string | null` | yes |  |
| `source_id` | `string | null` | yes |  |
| `project_id` | `string | null` | yes |  |
| `parent_artifact_id` | `string (uuid) | null` | yes |  |
| `tags` | `array<string>` | yes |  |
| `metadata` | `object` | yes |  |
| `created_at` | `string` | yes |  |
| `updated_at` | `string` | yes |  |

## `ArtifactStatusSchema`

Enum values: `"draft"`, `"saved"`, `"archived"`

## `ArtifactVersionSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string (uuid)` | yes |  |
| `artifact_id` | `unknown` | yes |  |
| `version` | `integer` | yes |  |
| `edited_by` | `unknown` | yes |  |
| `edit_source` | `enum("api" | "mcp" | "frontend" | "pipeline")` | yes |  |
| `content_markdown` | `string | null` | yes |  |
| `content_json` | `object | null` | yes |  |
| `title` | `string` | yes |  |
| `status` | `enum("draft" | "saved" | "archived")` | yes |  |
| `change_summary` | `string | null` | yes |  |
| `created_at` | `string` | yes |  |

## `AskRequestSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | `string` | yes |  |

## `AskResponseSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `answer` | `string` | yes |  |
| `substrateStats` | `object` | yes |  |

## `ClusterSearchRequestSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | `string` | yes |  |
| `match_threshold` | `number` | no |  |
| `limit` | `integer` | no |  |

## `CreateArtifactRequestSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `artifact_type` | `string` | yes |  |
| `title` | `string` | yes |  |
| `description` | `string` | no |  |
| `content_markdown` | `string` | no |  |
| `content_json` | `object` | no |  |
| `project_id` | `string (uuid)` | no |  |
| `parent_artifact_id` | `unknown` | no |  |
| `tags` | `array<string>` | no |  |
| `metadata` | `object` | no |  |

## `DeletedResponseSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `deleted` | `boolean` | yes |  |

## `ErrorSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | `string` | yes |  |

## `ExploreRequestSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `scope` | `enum("all" | "schema" | "clusters" | "knowledge")` | no |  |
| `include_samples` | `boolean` | no |  |

## `QueryRequestSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sql` | `string` | yes |  |
| `limit` | `integer` | no |  |

## `QueryResultSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rowCount` | `number` | yes |  |
| `truncated` | `boolean` | yes |  |
| `rows` | `array<object>` | yes |  |

## `RegisterWebhookRequestSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string (uri)` | yes |  |
| `events` | `array<enum("artifact.created" | "artifact.updated" | "artifact.status_changed" | "session.completed")>` | yes |  |

## `RememberRequestSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | `string` | yes |  |
| `source` | `enum("web" | "kg" | "reference_doc" | "bigquery" | "cluster")` | no |  |
| `company_name` | `string` | no |  |

## `RememberResponseSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `evidenceId` | `string` | yes |  |
| `totalEvidenceCount` | `number` | yes |  |
| `persisted` | `boolean` | yes |  |

## `SearchRequestSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | `string` | yes |  |
| `mode` | `enum("hybrid" | "semantic" | "keyword")` | no |  |
| `limit` | `integer` | no |  |
| `source_type` | `string` | no |  |

## `SearchResultSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `resultCount` | `number` | yes |  |
| `results` | `array<object>` | yes |  |

## `SessionIdHeader`

_Non-object schema, see OpenAPI spec for details._

## `SessionListItemSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes |  |
| `created_at` | `string` | yes |  |
| `updated_at` | `string` | yes |  |

## `SessionSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes |  |
| `business_id` | `string (uuid)` | yes |  |
| `user_id` | `unknown` | yes |  |
| `created_at` | `string` | yes |  |
| `updated_at` | `string` | yes |  |

## `SubstrateIntentSchema`

Enum values: `"answer_question"`, `"find_metrics"`, `"research_overview"`, `"summarize_research"`, `"evidence_for_writing"`, `"enrich_with_quotes"`, `"assess_viability"`

## `SubstrateQueryRequestSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `intent` | `enum("answer_question" | "find_metrics" | "research_overview" | "summarize_research" | "evidence_for_writing" | "enrich_with_quotes" | "assess_viability")` | yes |  |
| `query` | `string` | no |  |
| `limit` | `integer` | no |  |
| `source_filter` | `array<string>` | no |  |

## `UpdateArtifactRequestSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `string` | no |  |
| `description` | `string` | no |  |
| `status` | `enum("draft" | "saved" | "archived")` | no |  |
| `content_markdown` | `string` | no |  |
| `content_json` | `object` | no |  |
| `tags` | `array<string>` | no |  |
| `metadata` | `object` | no |  |
| `change_summary` | `string` | no |  |

## `WebhookDeliverySchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string (uuid)` | yes |  |
| `webhook_id` | `unknown` | yes |  |
| `event` | `string` | yes |  |
| `payload` | `object` | yes |  |
| `status_code` | `number | null` | yes |  |
| `attempt` | `integer` | yes |  |
| `error` | `string | null` | yes |  |
| `created_at` | `string` | yes |  |

## `WebhookEventSchema`

Enum values: `"artifact.created"`, `"artifact.updated"`, `"artifact.status_changed"`, `"session.completed"`

## `WebhookSchema`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string (uuid)` | yes |  |
| `business_id` | `unknown` | yes |  |
| `user_id` | `unknown` | yes |  |
| `url` | `string (uri)` | yes |  |
| `events` | `array<enum("artifact.created" | "artifact.updated" | "artifact.status_changed" | "session.completed")>` | yes |  |
| `active` | `boolean` | yes |  |
| `created_at` | `string` | yes |  |
| `secret` | `string` | no |  |