Customer Data Intake

Console-facing intake file catalog, upload, download, and schema registry endpoints.

The intake endpoints provide a console-facing file catalog and schema registry for structured customer data uploads. All endpoints are scoped to the authenticated workspace and use standard JWT workspace session authentication.

Files enter the intake catalog three ways: direct uploads through these endpoints, shareable upload links for non-technical customers, and automatic discovery from connected intake sources. Files landed by a source sync carry a batch association; direct uploads do not.

Files

List Files

Returns a paginated list of uploaded files. Results can be sorted by ingestion time, filename, status, dataset, or size, filtered by status, and searched by filename (case-insensitive substring match).

List Intake Files

get

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

limitinteger · min: 1 · max: 200OptionalDefault: 50

continuation_tokenintegerOptionalDefault: 0

sort_bystring · max: 64OptionalDefault: -ingested_at

statusstring · enum · nullableOptionalPossible values:

searchstring · max: 200 · nullableOptional

include_withdrawnbooleanOptionalDefault: false

Responses

200

Successful Response

application/json

has_morebooleanRequired

continuation_tokeninteger · nullableOptional

totalinteger · nullableOptional

422

Validation Error

application/json

get/v1/{workspace_id}/intake/files

HTTPcURLJavaScriptPython

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
}

Each file object carries a lifecycle status:

Status	Meaning
received	Upload accepted, not yet scanned
scanned	Malware scan passed
processing	Being validated and processed
curated	Validated and available downstream
rejected	Failed schema validation (see error_reason)
failed	Processing error (see error_reason)
held	Held for review

Upload File

Upload a file (multipart/form-data) to a registered dataset. The file is validated against the dataset's schema contract. Byte-identical re-uploads to the same dataset return the existing file (idempotent). For document datasets, pass the optional document_id form field to add a new version to an existing document; document_id is rejected with 422 for snapshot (tabular) datasets, which version at the dataset scope.

Upload Intake File

post

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

multipart/form-data

datasetstring · min: 2 · max: 63RequiredPattern: ^[a-z0-9][a-z0-9_-]*[a-z0-9]$

filestringRequired

document_idstring · uuid · nullableOptional

Responses

201

Successful Response

application/json

A file in the Files list (intake-ui-mvp-design.md §5.1).

idstring · uuidRequired

file_id — used for download.

filenamestringRequired

datasetstringRequired

Schema slug (UI label "Schema").

schema_versionstring · nullableOptional

The contract version this file validated against (e.g. v1).

statusstring · enumRequiredPossible values:

error_reasonstring · nullableOptional

Null unless rejected/failed.

size_bytesintegerRequired

ingested_atstringRequired

ISO-8601 timestamp the file was received.

document_idstring · uuid · nullableOptional

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.

versioninteger · nullableOptional

The file's version number (per-document for documents, per-dataset for snapshot). Lets the UI render a document's version history.

source_typestring · nullableOptional

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.

source_file_idstring · nullableOptional

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.

source_folder_pathstring · nullableOptional

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.

422

Validation Error

application/json

post/v1/{workspace_id}/intake/files

HTTPcURLJavaScriptPython

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"
}

Error Responses:

Status	Condition
413	File exceeds size limit (global 100 MB cap or schema-level max_size_mb)
422	No schema registered for the specified dataset, invalid filename, empty upload, or upload rejected by malware scan
503	Upload scanner unavailable

Download File

Download the original uploaded file bytes. The response is a binary download with a Content-Disposition: attachment header. Returns 404 if the file is not found in this workspace.

Download Intake File

get

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

file_idstring · uuidRequired

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/json

get/v1/{workspace_id}/intake/files/{file_id}/download

HTTPcURLJavaScriptPython

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

Schemas (Datasets)

List Schemas

Returns a paginated list of registered schemas, sortable by name, creation time, or schema version, and searchable by dataset name.

List Intake Datasets

get

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Query parameters

limitinteger · min: 1 · max: 200OptionalDefault: 50

continuation_tokenintegerOptionalDefault: 0

sort_bystring · max: 64OptionalDefault: name

searchstring · max: 200 · nullableOptional

Responses

200

Successful Response

application/json

has_morebooleanRequired

continuation_tokeninteger · nullableOptional

totalinteger · nullableOptional

422

Validation Error

application/json

get/v1/{workspace_id}/intake/datasets

HTTPcURLJavaScriptPython

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
}

Register Schema

Register a new schema contract for a dataset. A schema declares the dataset slug, the expected file type, and an optional maximum upload size. Datasets come in two shapes, inferred from the file type:

• Snapshot (tabular) datasets (csv, xls, xlsx) require a primary key (up to 32 column names) and a field list (up to 500 fields, each a column name plus a data type: str, int, float, bool, date, or datetime).
• Document datasets (e.g. pdf, docx, md) ignore the primary key and field list. They accept an optional set of accepted_file_types (mixing in a tabular type is rejected) and an optional document_processing config with an extraction_mode of text_extract (default), OCR, or hybrid, and a retain_source flag (default true).

Register Intake Schema

post

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Body

application/json

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).

namestring · min: 2 · max: 63RequiredPattern: ^[a-z0-9][a-z0-9_-]*[a-z0-9]$

file_typestring · min: 1 · max: 16RequiredPattern: ^[a-z0-9]+$

accepted_file_typesstring[] · max: 16Optional

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.

Default: []

primary_keystring[] · max: 32Optional

Snapshot only — the canonical PK column(s). Empty/ignored for documents.

Default: []

max_size_mbinteger · nullableOptional

Responses

201

Successful Response

application/json

A registered schema in the Schemas list (intake-ui-mvp-design.md §5.3).

namestringRequired

Dataset slug (UI label "Schema").

schema_versionstringRequired

field_countintegerRequired

file_typestringRequired

Primary/representative file type (the first accepted type).

accepted_file_typesstring[]Optional

Document datasets: the full accepted-type set (V265). Empty for snapshot or legacy single-type documents (the UI falls back to file_type).

Default: []

ingestion_modestringRequired

snapshot (CSV/Excel → CDC) or document (PDF/docx → extraction).

422

Validation Error

application/json

post/v1/{workspace_id}/intake/schema/register

HTTPcURLJavaScriptPython

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
  }
}

Error Responses:

Status	Condition
409	A schema with this name already exists in the workspace
422	Validation error: missing fields, unknown field types, primary key columns not in field list

External Integration Upload

Streaming binary upload for approved external integrations. The request body is the raw file bytes; metadata and a per-customer HMAC signature over the request headers are carried in headers:

Header	Value
x-amigo-intake-sha256	SHA-256 of the file content (64 hex chars)
x-amigo-intake-timestamp	Unix seconds
x-amigo-intake-signature	Hex HMAC signature
x-amigo-intake-customer-slug	Customer identifier slug
x-amigo-intake-filename	Original filename
x-amigo-intake-content-type	MIME type (optional; defaults to application/octet-stream)

Invalid or missing header values are rejected with 401.

Receive Intake File

post

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Header parameters

x-amigo-intake-sha256string · max: 64Required

x-amigo-intake-timestampstring · max: 20Required

x-amigo-intake-signaturestring · max: 512Required

x-amigo-intake-customer-slugstring · max: 63Required

x-amigo-intake-filenamestring · max: 256Required

x-amigo-intake-content-typestring · max: 128OptionalDefault: application/octet-stream

Responses

201

Successful Response

application/json

idstring · uuidRequired

volume_pathstringRequired

sha256stringRequired

size_bytesintegerRequired

scan_statusstringRequired

422

Validation Error

application/json

post/v1/{workspace_id}/intake/files/external

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/intake/files/external HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
x-amigo-intake-sha256: text
x-amigo-intake-timestamp: text
x-amigo-intake-signature: text
x-amigo-intake-customer-slug: text
x-amigo-intake-filename: text
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "volume_path": "text",
  "sha256": "text",
  "size_bytes": 1,
  "scan_status": "text"
}