Intake
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
500-ingested_atfalseSuccessful Response
Validation Error
GET /v1/{workspace_id}/intake/files HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"filename": "text",
"dataset": "text",
"schema_version": "text",
"status": "received",
"error_reason": "text",
"size_bytes": 1,
"ingested_at": "text",
"document_id": "123e4567-e89b-12d3-a456-426614174000",
"version": 1,
"source_type": "text",
"source_file_id": "text",
"source_folder_path": "text"
}
],
"has_more": true,
"continuation_token": 1,
"total": 1
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
^[a-z0-9][a-z0-9_-]*[a-z0-9]$Successful Response
A file in the Files list (intake-ui-mvp-design.md §5.1).
file_id — used for download.
Schema slug (UI label "Schema").
The contract version this file validated against (e.g. v1).
Null unless rejected/failed.
ISO-8601 timestamp the file was received.
The document this version belongs to (§5.9). Null for snapshot/CSV rows; set for documents — the console groups versions by it and the version chain.
The file's version number (per-document for documents, per-dataset for snapshot). Lets the UI render a document's version history.
Origin of the document this version belongs to — manual for console
uploads, google_shared_drive for the Drive connector (V269). Null for
snapshot/CSV rows.
The source's stable external id (e.g. the Google Drive file id) for the document. Lets the console show provenance and confirm a re-synced file bumped the same document. Null for manual uploads and snapshot rows.
Where the file lived within the mapped Drive folder tree (V279) — the
relative path, folder names joined by / (e.g. clinical/notes); ''
at the mapped root. Lets the console show the original folder structure. Null
for manual uploads and snapshot rows.
Validation Error
POST /v1/{workspace_id}/intake/files HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 85
{
"dataset": "text",
"file": "text",
"document_id": "123e4567-e89b-12d3-a456-426614174000"
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"filename": "text",
"dataset": "text",
"schema_version": "text",
"status": "received",
"error_reason": "text",
"size_bytes": 1,
"ingested_at": "text",
"document_id": "123e4567-e89b-12d3-a456-426614174000",
"version": 1,
"source_type": "text",
"source_file_id": "text",
"source_folder_path": "text"
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Validation Error
GET /v1/{workspace_id}/intake/files/{file_id}/download HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
500nameSuccessful Response
Validation Error
GET /v1/{workspace_id}/intake/datasets HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"name": "text",
"schema_version": "text",
"field_count": 1,
"file_type": "text",
"accepted_file_types": [
"text"
],
"ingestion_mode": "text",
"limits": {
"max_size_mb": 1
}
}
],
"has_more": true,
"continuation_token": 1,
"total": 1
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
500-created_tsSuccessful Response
Validation Error
GET /v1/{workspace_id}/intake/sources HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"source_type": "text",
"display_name": "text",
"drive_id": "text",
"folders": [
{
"folder_id": "text",
"dataset": "text",
"contains_phi": true
}
],
"impersonate_subject": "text",
"status": "text",
"created_ts": "text"
}
],
"has_more": true,
"continuation_token": 1,
"total": 1
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Register a Google Shared Drive intake source (design §3).
The credential is not part of the wire contract and nothing needs provisioning:
the source authenticates as the unified platform-infra intake service account,
impersonated from the pod's workload identity. Grant access Drive-side — share
the folder with that SA's email, or set impersonate_subject for the DWD
model. drive_id is optional (resolved at sync if omitted).
Successful Response
A registered intake source (Sources list).
source_id.
DWD impersonation subject, if this source authenticates via domain-wide delegation.
ISO-8601 timestamp.
Validation Error
POST /v1/{workspace_id}/intake/sources HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 140
{
"display_name": "text",
"drive_id": "text",
"folders": [
{
"folder_id": "text",
"dataset": "text",
"contains_phi": true
}
],
"impersonate_subject": "text"
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"source_type": "text",
"display_name": "text",
"drive_id": "text",
"folders": [
{
"folder_id": "text",
"dataset": "text",
"contains_phi": true
}
],
"impersonate_subject": "text",
"status": "text",
"created_ts": "text"
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Validation Error
POST /v1/{workspace_id}/intake/sources/{source_id}/sync HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"batches": [
{
"batch_id": "123e4567-e89b-12d3-a456-426614174000",
"dataset": "text",
"files_found": 1,
"status": "text"
}
]
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Create Schema payload (intake-ui-mvp-design.md §5.4, §5.9).
ingestion_mode is inferred from file_type (csv/xls/xlsx → snapshot;
else document) — not part of the wire contract. Snapshot datasets require
primary_key + schema; document datasets take an optional
document_processing config and ignore primary_key/schema. The backend
applies the other hidden defaults (on_schema_change=additive,
schema_version auto).
^[a-z0-9][a-z0-9_-]*[a-z0-9]$^[a-z0-9]+$Document only — the SET of accepted file types (V265, e.g.
["pdf","docx","md"]). Empty → single-type (just file_type).
file_type is included as the primary. Mixing in a tabular type
(csv/xls/xlsx) is rejected; snapshot datasets are single-type.
[]Snapshot only — the canonical PK column(s). Empty/ignored for documents.
[]Successful Response
A registered schema in the Schemas list (intake-ui-mvp-design.md §5.3).
Dataset slug (UI label "Schema").
Primary/representative file type (the first accepted type).
Document datasets: the full accepted-type set (V265). Empty for snapshot
or legacy single-type documents (the UI falls back to file_type).
[]snapshot (CSV/Excel → CDC) or document (PDF/docx → extraction).
Validation Error
POST /v1/{workspace_id}/intake/schema/register HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 222
{
"name": "text",
"file_type": "text",
"accepted_file_types": [
"text"
],
"primary_key": [
"text"
],
"schema": [
{
"name": "text",
"type": "str"
}
],
"document_processing": {
"retain_source": true,
"extraction_mode": "text_extract"
},
"max_size_mb": 1
}{
"name": "text",
"schema_version": "text",
"field_count": 1,
"file_type": "text",
"accepted_file_types": [
"text"
],
"ingestion_mode": "text",
"limits": {
"max_size_mb": 1
}
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
500-created_tsSuccessful Response
Validation Error
GET /v1/{workspace_id}/intake/batches HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"source_id": "123e4567-e89b-12d3-a456-426614174000",
"dataset": "text",
"status": "text",
"files_found": 1,
"created_ts": "text"
}
],
"has_more": true,
"continuation_token": 1,
"total": 1
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
batch_id.
discovered | ready | processing | completed | failed.
Validation Error
GET /v1/{workspace_id}/intake/batches/{batch_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"source_id": "123e4567-e89b-12d3-a456-426614174000",
"dataset": "text",
"status": "text",
"files_found": 1,
"created_ts": "text",
"files": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"filename": "text",
"dataset": "text",
"schema_version": "text",
"status": "received",
"error_reason": "text",
"size_bytes": 1,
"ingested_at": "text",
"document_id": "123e4567-e89b-12d3-a456-426614174000",
"version": 1,
"source_type": "text",
"source_file_id": "text",
"source_folder_path": "text"
}
]
}The per-file params the batch-extract job needs to process every still- received file in one run. Same workspace-scoped auth as the write-back (the job holds the batch's agent-session token). Documents only — snapshot/CSV batches process in version order via the chained per-file path, not here.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Per-file extraction params for a document batch's still-received files —
consumed by the batch-extract job, which runs ONCE per batch and extracts
every file (instead of one run-now per file, which blows the request/gateway
timeout for large batches). Authenticated by the same short-lived
workspace-scoped token as the status write-back. document_processing is
dataset-wide (the contract); file_type is per-file (V265 multi-type).
Source provenance mirrors the single-file path (resolve_source_identity, PHI gate): source_file_id/source_url (opaque ids) always populate; source_folder_path
- filename (operator-named free text) populate ONLY for contains_phi=false datasets — otherwise they stay None, so PHI never leaves the Lakebase row.
Validation Error
GET /v1/{workspace_id}/intake/batches/{batch_id}/processing-manifest HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"document_processing": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"files": [
{
"file_id": "123e4567-e89b-12d3-a456-426614174000",
"document_id": "123e4567-e89b-12d3-a456-426614174000",
"version": 1,
"source_path": "text",
"file_type": "text",
"content_type": "text",
"sha256": "text",
"size_bytes": 1,
"ingested_at": "text",
"contract_id": "123e4567-e89b-12d3-a456-426614174000",
"contract_version": "text",
"source_file_id": "text",
"source_url": "text",
"source_folder_path": "text",
"filename": "text"
}
]
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
A source-sync batch (Batches list / detail).
batch_id.
discovered | ready | processing | completed | failed.
Validation Error
POST /v1/{workspace_id}/intake/batches/{batch_id}/process HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"source_id": "123e4567-e89b-12d3-a456-426614174000",
"dataset": "text",
"status": "text",
"files_found": 1,
"created_ts": "text"
}Trigger the intake → customer-data materializer for this workspace.
Fires the materializer Databricks job (run-now); it rescans the workspace's curated intake files and (re)materializes each snapshot dataset into customer_data_<env>.<workspace_id>.<dataset>. Every write is an idempotent keyed MERGE / full overwrite, so a re-click is safe. Optionally scope to one dataset; omit for all curated snapshot datasets. Returns 202 with the job run_id (null when the job is not configured in this environment). Same auth gate as POST /batches/{batch_id}/process.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
^[a-z0-9][a-z0-9_-]*[a-z0-9]$Successful Response
Validation Error
POST /v1/{workspace_id}/intake/materialize HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 18
{
"dataset": "text"
}{
"run_id": 1
}Run the customer-facing dataset update flow.
This is the one-click orchestration path for the console: check mapped Drive folders, prepare any newly landed files, and publish immediately when no preparation is needed. If preparation is async, the run remains durable and is advanced by file write-backs or by refresh.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
^[a-z0-9][a-z0-9_-]*[a-z0-9]$Successful Response
Durable status for one dataset update action.
Validation Error
POST /v1/{workspace_id}/intake/datasets/{dataset}/update HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"dataset": "text",
"status": "checking_drive",
"source_ids": [
"123e4567-e89b-12d3-a456-426614174000"
],
"batch_ids": [
"123e4567-e89b-12d3-a456-426614174000"
],
"materialize_run_id": 1,
"error": "text",
"created_at": "text",
"updated_at": "text",
"completed_at": "text"
}API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Durable status for one dataset update action.
Validation Error
GET /v1/{workspace_id}/intake/update-runs/{run_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"dataset": "text",
"status": "checking_drive",
"source_ids": [
"123e4567-e89b-12d3-a456-426614174000"
],
"batch_ids": [
"123e4567-e89b-12d3-a456-426614174000"
],
"materialize_run_id": 1,
"error": "text",
"created_at": "text",
"updated_at": "text",
"completed_at": "text"
}Per-dataset materialization status for the workspace's Destinations tab.
Lists each registered dataset alongside its customer-data destination table's status — materialized (with row count + last-write time) or not_materialized (no table yet). The dataset list + pagination mirror GET /datasets (the contracts registry); the destination status is read from the customer_data_<env> catalog via the SQL warehouse. Member read.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
500nameSuccessful Response
Validation Error
GET /v1/{workspace_id}/intake/materializations HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"dataset": "text",
"ingestion_mode": "text",
"status": "materialized",
"row_count": 1,
"last_materialized_at": "text"
}
],
"has_more": true,
"continuation_token": 1,
"total": 1
}Advance a file's status from the async CDC/extraction job (P4).
The job authenticates with the workspace's API key (Bearer) over the standard Databricks→platform-api path — so RLS scopes the update to that workspace. Moves the row to its terminal verdict and records the curated/cdc paths. For a batch-sourced file, advances its batch (chain the next snapshot version + roll up) once the verdict is terminal.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Status advance written by the async CDC job (P4).
The job posts the terminal verdict after conform/validate/diff. error_reason
must be PHI-safe (the engine reports column + type + counts only — never cell
values). curated_path/cdc_path are set only on a clean verdict.
^[A-Za-z0-9/._-]+$^[A-Za-z0-9/._-]+$Successful Response
A file in the Files list (intake-ui-mvp-design.md §5.1).
file_id — used for download.
Schema slug (UI label "Schema").
The contract version this file validated against (e.g. v1).
Null unless rejected/failed.
ISO-8601 timestamp the file was received.
The document this version belongs to (§5.9). Null for snapshot/CSV rows; set for documents — the console groups versions by it and the version chain.
The file's version number (per-document for documents, per-dataset for snapshot). Lets the UI render a document's version history.
Origin of the document this version belongs to — manual for console
uploads, google_shared_drive for the Drive connector (V269). Null for
snapshot/CSV rows.
The source's stable external id (e.g. the Google Drive file id) for the document. Lets the console show provenance and confirm a re-synced file bumped the same document. Null for manual uploads and snapshot rows.
Where the file lived within the mapped Drive folder tree (V279) — the
relative path, folder names joined by / (e.g. clinical/notes); ''
at the mapped root. Lets the console show the original folder structure. Null
for manual uploads and snapshot rows.
Validation Error
POST /v1/{workspace_id}/intake/files/{file_id}/status HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 83
{
"status": "received",
"error_reason": "text",
"curated_path": "text",
"cdc_path": "text"
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"filename": "text",
"dataset": "text",
"schema_version": "text",
"status": "received",
"error_reason": "text",
"size_bytes": 1,
"ingested_at": "text",
"document_id": "123e4567-e89b-12d3-a456-426614174000",
"version": 1,
"source_type": "text",
"source_file_id": "text",
"source_folder_path": "text"
}Last updated
Was this helpful?