> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/api-reference/readme/platform/intake.md).

# Intake

## GET /v1/{workspace\_id}/intake/files

> List Intake Files

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"_FileStatus":{"type":"string","enum":["received","scanned","processing","curated","rejected","failed","held"]},"PaginatedResponse_IntakeFileRow_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/IntakeFileRow"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"}},"type":"object","required":["items","has_more"],"title":"PaginatedResponse[IntakeFileRow]"},"IntakeFileRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"file_id — used for download."},"filename":{"type":"string","title":"Filename"},"dataset":{"type":"string","title":"Dataset","description":"Schema slug (UI label \"Schema\")."},"schema_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schema Version","description":"The contract version this file validated against (e.g. ``v1``)."},"status":{"$ref":"#/components/schemas/_FileStatus"},"error_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Reason","description":"Null unless rejected/failed."},"size_bytes":{"type":"integer","title":"Size Bytes"},"ingested_at":{"type":"string","title":"Ingested At","description":"ISO-8601 timestamp the file was received."},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id","description":"The document this version belongs to (§5.9). Null for snapshot/CSV rows;\nset for documents — the console groups versions by it and the version chain."},"version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Version","description":"The file's version number (per-document for documents, per-dataset for\nsnapshot). Lets the UI render a document's version history."},"source_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Type","description":"Origin of the document this version belongs to — ``manual`` for console\nuploads, ``google_shared_drive`` for the Drive connector (V269). Null for\nsnapshot/CSV rows."},"source_file_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source File Id","description":"The source's stable external id (e.g. the Google Drive file id) for the\ndocument. Lets the console show provenance and confirm a re-synced file\nbumped the *same* document. Null for manual uploads and snapshot rows."},"source_folder_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Folder Path","description":"Where the file lived within the mapped Drive folder tree (V279) — the\nrelative path, folder names joined by ``/`` (e.g. ``clinical/notes``); ``''``\nat the mapped root. Lets the console show the original folder structure. Null\nfor manual uploads and snapshot rows."}},"type":"object","required":["id","filename","dataset","status","size_bytes","ingested_at"],"title":"IntakeFileRow","description":"A file in the Files list (intake-ui-mvp-design.md §5.1)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/intake/files":{"get":{"tags":["Intake"],"summary":"List Intake Files","operationId":"list_intake_files_v1__workspace_id__intake_files_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Continuation Token"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","maxLength":64,"default":"-ingested_at","title":"Sort By"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/_FileStatus"},{"type":"null"}],"title":"Status"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Search"}},{"name":"include_withdrawn","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Withdrawn"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_IntakeFileRow_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## POST /v1/{workspace\_id}/intake/files

> Upload Intake File

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"Body_upload_intake_file_v1__workspace_id__intake_files_post":{"properties":{"dataset":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$","title":"Dataset"},"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id"}},"type":"object","required":["dataset","file"],"title":"Body_upload_intake_file_v1__workspace_id__intake_files_post"},"IntakeFileRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"file_id — used for download."},"filename":{"type":"string","title":"Filename"},"dataset":{"type":"string","title":"Dataset","description":"Schema slug (UI label \"Schema\")."},"schema_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schema Version","description":"The contract version this file validated against (e.g. ``v1``)."},"status":{"$ref":"#/components/schemas/_FileStatus"},"error_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Reason","description":"Null unless rejected/failed."},"size_bytes":{"type":"integer","title":"Size Bytes"},"ingested_at":{"type":"string","title":"Ingested At","description":"ISO-8601 timestamp the file was received."},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id","description":"The document this version belongs to (§5.9). Null for snapshot/CSV rows;\nset for documents — the console groups versions by it and the version chain."},"version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Version","description":"The file's version number (per-document for documents, per-dataset for\nsnapshot). Lets the UI render a document's version history."},"source_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Type","description":"Origin of the document this version belongs to — ``manual`` for console\nuploads, ``google_shared_drive`` for the Drive connector (V269). Null for\nsnapshot/CSV rows."},"source_file_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source File Id","description":"The source's stable external id (e.g. the Google Drive file id) for the\ndocument. Lets the console show provenance and confirm a re-synced file\nbumped the *same* document. Null for manual uploads and snapshot rows."},"source_folder_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Folder Path","description":"Where the file lived within the mapped Drive folder tree (V279) — the\nrelative path, folder names joined by ``/`` (e.g. ``clinical/notes``); ``''``\nat the mapped root. Lets the console show the original folder structure. Null\nfor manual uploads and snapshot rows."}},"type":"object","required":["id","filename","dataset","status","size_bytes","ingested_at"],"title":"IntakeFileRow","description":"A file in the Files list (intake-ui-mvp-design.md §5.1)."},"_FileStatus":{"type":"string","enum":["received","scanned","processing","curated","rejected","failed","held"]},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/intake/files":{"post":{"tags":["Intake"],"summary":"Upload Intake File","operationId":"upload_intake_file_v1__workspace_id__intake_files_post","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_intake_file_v1__workspace_id__intake_files_post"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeFileRow"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## GET /v1/{workspace\_id}/intake/files/{file\_id}/download

> Download Intake File

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/intake/files/{file_id}/download":{"get":{"tags":["Intake"],"summary":"Download Intake File","operationId":"download_intake_file_v1__workspace_id__intake_files__file_id__download_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"file_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"File Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /v1/{workspace\_id}/intake/datasets

> List Intake Datasets

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"PaginatedResponse_DatasetRow_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/DatasetRow"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"}},"type":"object","required":["items","has_more"],"title":"PaginatedResponse[DatasetRow]"},"DatasetRow":{"properties":{"name":{"type":"string","title":"Name","description":"Dataset slug (UI label \"Schema\")."},"schema_version":{"type":"string","title":"Schema Version"},"field_count":{"type":"integer","title":"Field Count"},"file_type":{"type":"string","title":"File Type","description":"Primary/representative file type (the first accepted type)."},"accepted_file_types":{"items":{"type":"string"},"type":"array","title":"Accepted File Types","description":"Document datasets: the full accepted-type set (V265). Empty for snapshot\nor legacy single-type documents (the UI falls back to ``file_type``).","default":[]},"ingestion_mode":{"type":"string","title":"Ingestion Mode","description":"`snapshot` (CSV/Excel → CDC) or `document` (PDF/docx → extraction)."},"limits":{"$ref":"#/components/schemas/Limits"}},"type":"object","required":["name","schema_version","field_count","file_type","ingestion_mode","limits"],"title":"DatasetRow","description":"A registered schema in the Schemas list (intake-ui-mvp-design.md §5.3)."},"Limits":{"properties":{"max_size_mb":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Size Mb"}},"type":"object","title":"Limits"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/intake/datasets":{"get":{"tags":["Intake"],"summary":"List Intake Datasets","operationId":"list_intake_datasets_v1__workspace_id__intake_datasets_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Continuation Token"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","maxLength":64,"default":"name","title":"Sort By"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Search"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_DatasetRow_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /v1/{workspace\_id}/intake/sources

> List Intake Sources

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"PaginatedResponse_IntakeSourceRow_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/IntakeSourceRow"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"}},"type":"object","required":["items","has_more"],"title":"PaginatedResponse[IntakeSourceRow]"},"IntakeSourceRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"source_id."},"source_type":{"type":"string","title":"Source Type"},"display_name":{"type":"string","title":"Display Name"},"drive_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Drive Id"},"folders":{"items":{"$ref":"#/components/schemas/DriveFolderMapping"},"type":"array","title":"Folders"},"impersonate_subject":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Impersonate Subject","description":"DWD impersonation subject, if this source authenticates via domain-wide delegation."},"status":{"type":"string","title":"Status"},"created_ts":{"type":"string","title":"Created Ts","description":"ISO-8601 timestamp."}},"type":"object","required":["id","source_type","display_name","folders","status","created_ts"],"title":"IntakeSourceRow","description":"A registered intake source (Sources list)."},"DriveFolderMapping":{"properties":{"folder_id":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9_-]+$","title":"Folder Id"},"dataset":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$","title":"Dataset"},"contains_phi":{"type":"boolean","title":"Contains Phi","default":true}},"type":"object","required":["folder_id","dataset"],"title":"DriveFolderMapping","description":"One Google Drive folder ↔ one intake dataset.\n\n``folder_id`` is the Drive folder id (the identity — never the folder name,\nwhich can be renamed/moved). One folder maps to exactly one dataset."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/intake/sources":{"get":{"tags":["Intake"],"summary":"List Intake Sources","operationId":"list_intake_sources_v1__workspace_id__intake_sources_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Continuation Token"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","maxLength":64,"default":"-created_ts","title":"Sort By"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_IntakeSourceRow_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## POST /v1/{workspace\_id}/intake/sources

> Register Intake Source

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RegisterSourceRequest":{"properties":{"display_name":{"type":"string","maxLength":200,"minLength":1,"title":"Display Name"},"drive_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Drive Id"},"folders":{"items":{"$ref":"#/components/schemas/DriveFolderMapping"},"type":"array","maxItems":100,"minItems":1,"title":"Folders"},"impersonate_subject":{"anyOf":[{"type":"string","maxLength":320},{"type":"null"}],"title":"Impersonate Subject"}},"type":"object","required":["display_name","folders"],"title":"RegisterSourceRequest","description":"Register a Google Shared Drive intake source (design §3).\n\nThe credential is not part of the wire contract and nothing needs provisioning:\nthe source authenticates as the unified platform-infra intake service account,\nimpersonated from the pod's workload identity. Grant access Drive-side — share\nthe folder with that SA's email, or set ``impersonate_subject`` for the DWD\nmodel. ``drive_id`` is optional (resolved at sync if omitted)."},"DriveFolderMapping":{"properties":{"folder_id":{"type":"string","maxLength":256,"minLength":1,"pattern":"^[A-Za-z0-9_-]+$","title":"Folder Id"},"dataset":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$","title":"Dataset"},"contains_phi":{"type":"boolean","title":"Contains Phi","default":true}},"type":"object","required":["folder_id","dataset"],"title":"DriveFolderMapping","description":"One Google Drive folder ↔ one intake dataset.\n\n``folder_id`` is the Drive folder id (the identity — never the folder name,\nwhich can be renamed/moved). One folder maps to exactly one dataset."},"IntakeSourceRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"source_id."},"source_type":{"type":"string","title":"Source Type"},"display_name":{"type":"string","title":"Display Name"},"drive_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Drive Id"},"folders":{"items":{"$ref":"#/components/schemas/DriveFolderMapping"},"type":"array","title":"Folders"},"impersonate_subject":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Impersonate Subject","description":"DWD impersonation subject, if this source authenticates via domain-wide delegation."},"status":{"type":"string","title":"Status"},"created_ts":{"type":"string","title":"Created Ts","description":"ISO-8601 timestamp."}},"type":"object","required":["id","source_type","display_name","folders","status","created_ts"],"title":"IntakeSourceRow","description":"A registered intake source (Sources list)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/intake/sources":{"post":{"tags":["Intake"],"summary":"Register Intake Source","operationId":"register_intake_source_v1__workspace_id__intake_sources_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterSourceRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeSourceRow"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Delete Intake Source

> Remove a source registration without deleting upstream files or imported data.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/intake/sources/{source_id}":{"delete":{"tags":["Intake"],"summary":"Delete Intake Source","description":"Remove a source registration without deleting upstream files or imported data.","operationId":"delete_intake_source_v1__workspace_id__intake_sources__source_id__delete","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"source_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Source Id"}}],"responses":{"204":{"description":"Successful Response"},"403":{"description":"Write permission required"},"404":{"description":"Source not found"},"409":{"description":"Source operation in progress"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"503":{"description":"Coordination unavailable"}}}}}}
```

## POST /v1/{workspace\_id}/intake/sources/{source\_id}/sync

> Sync Intake Source

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"SourceSyncResponse":{"properties":{"batches":{"items":{"$ref":"#/components/schemas/SyncBatchRow"},"type":"array","title":"Batches"}},"type":"object","required":["batches"],"title":"SourceSyncResponse"},"SyncBatchRow":{"properties":{"batch_id":{"type":"string","format":"uuid","title":"Batch Id"},"dataset":{"type":"string","title":"Dataset"},"files_found":{"type":"integer","title":"Files Found"},"status":{"type":"string","title":"Status"}},"type":"object","required":["batch_id","dataset","files_found","status"],"title":"SyncBatchRow","description":"One batch produced by a source sync (one per mapped folder/dataset)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/intake/sources/{source_id}/sync":{"post":{"tags":["Intake"],"summary":"Sync Intake Source","operationId":"sync_intake_source_v1__workspace_id__intake_sources__source_id__sync_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"source_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Source Id"}}],"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceSyncResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## POST /v1/{workspace\_id}/intake/schema/register

> Register Intake Schema

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RegisterSchemaRequest":{"properties":{"name":{"$ref":"#/components/schemas/_DatasetSlug"},"file_type":{"$ref":"#/components/schemas/_FileType"},"accepted_file_types":{"items":{"$ref":"#/components/schemas/_FileType"},"type":"array","maxItems":16,"title":"Accepted File Types","description":"Document only — the SET of accepted file types (V265, e.g.\n``[\"pdf\",\"docx\",\"md\"]``). Empty → single-type (just ``file_type``).\n``file_type`` is included as the primary. Mixing in a tabular type\n(csv/xls/xlsx) is rejected; snapshot datasets are single-type.","default":[]},"primary_key":{"items":{"$ref":"#/components/schemas/_FieldName"},"type":"array","maxItems":32,"title":"Primary Key","description":"Snapshot only — the canonical PK column(s). Empty/ignored for documents.","default":[]},"schema":{"items":{"$ref":"#/components/schemas/SchemaFieldSpec"},"type":"array","maxItems":500,"title":"Schema","description":"Snapshot only — canonical field list ``[{name, type}]`` (wire key ``schema``).","default":[]},"document_processing":{"anyOf":[{"$ref":"#/components/schemas/DocumentProcessingSpec"},{"type":"null"}],"description":"Document only — extraction config; defaulted server-side when omitted."},"max_size_mb":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Size Mb"}},"type":"object","required":["name","file_type"],"title":"RegisterSchemaRequest","description":"Create Schema payload (intake-ui-mvp-design.md §5.4, §5.9).\n\n``ingestion_mode`` is inferred from ``file_type`` (csv/xls/xlsx → snapshot;\nelse document) — not part of the wire contract. Snapshot datasets require\n``primary_key`` + ``schema``; document datasets take an optional\n``document_processing`` config and ignore primary_key/schema. The backend\napplies the other hidden defaults (``on_schema_change=additive``,\n``schema_version`` auto)."},"_DatasetSlug":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$"},"_FileType":{"type":"string","maxLength":16,"minLength":1,"pattern":"^[a-z0-9]+$"},"_FieldName":{"type":"string","maxLength":128,"minLength":1,"pattern":"^[A-Za-z_][A-Za-z0-9_]*$"},"SchemaFieldSpec":{"properties":{"name":{"$ref":"#/components/schemas/_FieldName"},"type":{"$ref":"#/components/schemas/IntakeFieldType"}},"type":"object","required":["name","type"],"title":"SchemaFieldSpec"},"IntakeFieldType":{"type":"string","enum":["str","int","float","bool","date","datetime"],"title":"IntakeFieldType","description":"Allowed ``schema[].type`` values for a registered contract.\n\nConfirmed set (intake-ui-mvp design contract point #1): scalars plus\nISO date/datetime. Coercion semantics live in :func:`_coerces`."},"DocumentProcessingSpec":{"properties":{"retain_source":{"type":"boolean","title":"Retain Source","default":true},"extraction_mode":{"type":"string","enum":["text_extract","OCR","hybrid"],"title":"Extraction Mode","default":"text_extract"}},"type":"object","title":"DocumentProcessingSpec","description":"Processing config for a document dataset (``ingestion_mode=document``).\n\nDocuments have no schema/primary-key/CDC; this is what the contract carries\ninstead (docs/plans/intake_file_processing_pipeline.md §5.9). Page-split /\noutput-metadata rules are stored in the same jsonb and may be added later\nwithout a migration."},"DatasetRow":{"properties":{"name":{"type":"string","title":"Name","description":"Dataset slug (UI label \"Schema\")."},"schema_version":{"type":"string","title":"Schema Version"},"field_count":{"type":"integer","title":"Field Count"},"file_type":{"type":"string","title":"File Type","description":"Primary/representative file type (the first accepted type)."},"accepted_file_types":{"items":{"type":"string"},"type":"array","title":"Accepted File Types","description":"Document datasets: the full accepted-type set (V265). Empty for snapshot\nor legacy single-type documents (the UI falls back to ``file_type``).","default":[]},"ingestion_mode":{"type":"string","title":"Ingestion Mode","description":"`snapshot` (CSV/Excel → CDC) or `document` (PDF/docx → extraction)."},"limits":{"$ref":"#/components/schemas/Limits"}},"type":"object","required":["name","schema_version","field_count","file_type","ingestion_mode","limits"],"title":"DatasetRow","description":"A registered schema in the Schemas list (intake-ui-mvp-design.md §5.3)."},"Limits":{"properties":{"max_size_mb":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Size Mb"}},"type":"object","title":"Limits"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/intake/schema/register":{"post":{"tags":["Intake"],"summary":"Register Intake Schema","operationId":"register_intake_schema_v1__workspace_id__intake_schema_register_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterSchemaRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetRow"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## GET /v1/{workspace\_id}/intake/batches

> List Intake Batches

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"PaginatedResponse_BatchRow_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/BatchRow"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"}},"type":"object","required":["items","has_more"],"title":"PaginatedResponse[BatchRow]"},"BatchRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"batch_id."},"source_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Id"},"dataset":{"type":"string","title":"Dataset"},"status":{"type":"string","title":"Status","description":"discovered | ready | processing | completed | failed."},"files_found":{"type":"integer","title":"Files Found"},"created_ts":{"type":"string","title":"Created Ts"}},"type":"object","required":["id","dataset","status","files_found","created_ts"],"title":"BatchRow","description":"A source-sync batch (Batches list / detail)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/intake/batches":{"get":{"tags":["Intake"],"summary":"List Intake Batches","operationId":"list_intake_batches_v1__workspace_id__intake_batches_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Continuation Token"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","maxLength":64,"default":"-created_ts","title":"Sort By"}},{"name":"source_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_BatchRow_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /v1/{workspace\_id}/intake/batches/{batch\_id}

> Get Intake Batch

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"BatchDetail":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"batch_id."},"source_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Id"},"dataset":{"type":"string","title":"Dataset"},"status":{"type":"string","title":"Status","description":"discovered | ready | processing | completed | failed."},"files_found":{"type":"integer","title":"Files Found"},"created_ts":{"type":"string","title":"Created Ts"},"files":{"items":{"$ref":"#/components/schemas/IntakeFileRow"},"type":"array","title":"Files","default":[]}},"type":"object","required":["id","dataset","status","files_found","created_ts"],"title":"BatchDetail"},"IntakeFileRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"file_id — used for download."},"filename":{"type":"string","title":"Filename"},"dataset":{"type":"string","title":"Dataset","description":"Schema slug (UI label \"Schema\")."},"schema_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schema Version","description":"The contract version this file validated against (e.g. ``v1``)."},"status":{"$ref":"#/components/schemas/_FileStatus"},"error_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Reason","description":"Null unless rejected/failed."},"size_bytes":{"type":"integer","title":"Size Bytes"},"ingested_at":{"type":"string","title":"Ingested At","description":"ISO-8601 timestamp the file was received."},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id","description":"The document this version belongs to (§5.9). Null for snapshot/CSV rows;\nset for documents — the console groups versions by it and the version chain."},"version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Version","description":"The file's version number (per-document for documents, per-dataset for\nsnapshot). Lets the UI render a document's version history."},"source_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Type","description":"Origin of the document this version belongs to — ``manual`` for console\nuploads, ``google_shared_drive`` for the Drive connector (V269). Null for\nsnapshot/CSV rows."},"source_file_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source File Id","description":"The source's stable external id (e.g. the Google Drive file id) for the\ndocument. Lets the console show provenance and confirm a re-synced file\nbumped the *same* document. Null for manual uploads and snapshot rows."},"source_folder_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Folder Path","description":"Where the file lived within the mapped Drive folder tree (V279) — the\nrelative path, folder names joined by ``/`` (e.g. ``clinical/notes``); ``''``\nat the mapped root. Lets the console show the original folder structure. Null\nfor manual uploads and snapshot rows."}},"type":"object","required":["id","filename","dataset","status","size_bytes","ingested_at"],"title":"IntakeFileRow","description":"A file in the Files list (intake-ui-mvp-design.md §5.1)."},"_FileStatus":{"type":"string","enum":["received","scanned","processing","curated","rejected","failed","held"]},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/intake/batches/{batch_id}":{"get":{"tags":["Intake"],"summary":"Get Intake Batch","operationId":"get_intake_batch_v1__workspace_id__intake_batches__batch_id__get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Batch Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Get Batch Processing Manifest

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"BatchProcessingManifest":{"properties":{"document_processing":{"additionalProperties":true,"type":"object","title":"Document Processing"},"files":{"items":{"$ref":"#/components/schemas/FileEntry"},"type":"array","title":"Files"}},"type":"object","required":["document_processing","files"],"title":"BatchProcessingManifest","description":"Per-file extraction params for a document batch's still-``received`` files —\nconsumed by the batch-extract job, which runs ONCE per batch and extracts\nevery file (instead of one run-now per file, which blows the request/gateway\ntimeout for large batches). Authenticated by the same short-lived\nworkspace-scoped token as the status write-back. ``document_processing`` is\ndataset-wide (the contract); ``file_type`` is per-file (V265 multi-type).\n\nSource provenance mirrors the single-file path (resolve_source_identity, PHI\ngate): source_file_id/source_url (opaque ids) always populate; source_folder_path\n+ filename (operator-named free text) populate ONLY for contains_phi=false\ndatasets — otherwise they stay None, so PHI never leaves the Lakebase row."},"FileEntry":{"properties":{"file_id":{"type":"string","format":"uuid","title":"File Id"},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id"},"version":{"type":"integer","title":"Version"},"source_path":{"type":"string","title":"Source Path"},"file_type":{"type":"string","title":"File Type"},"content_type":{"type":"string","title":"Content Type"},"sha256":{"type":"string","title":"Sha256"},"size_bytes":{"type":"integer","title":"Size Bytes"},"ingested_at":{"type":"string","title":"Ingested At"},"contract_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Contract Id"},"contract_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contract Version"},"source_file_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source File Id"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"source_folder_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Folder Path"},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename"}},"type":"object","required":["file_id","version","source_path","file_type","content_type","sha256","size_bytes","ingested_at"],"title":"FileEntry"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/intake/batches/{batch_id}/processing-manifest":{"get":{"tags":["Intake"],"summary":"Get Batch Processing Manifest","description":"The per-file params the batch-extract job needs to process every still-\n``received`` file in one run. Same workspace-scoped auth as the write-back\n(the job holds the batch's agent-session token). Documents only — snapshot/CSV\nbatches process in version order via the chained per-file path, not here.","operationId":"get_batch_processing_manifest_v1__workspace_id__intake_batches__batch_id__processing_manifest_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Batch Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchProcessingManifest"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## POST /v1/{workspace\_id}/intake/batches/{batch\_id}/process

> Process Intake Batch

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"BatchRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"batch_id."},"source_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Id"},"dataset":{"type":"string","title":"Dataset"},"status":{"type":"string","title":"Status","description":"discovered | ready | processing | completed | failed."},"files_found":{"type":"integer","title":"Files Found"},"created_ts":{"type":"string","title":"Created Ts"}},"type":"object","required":["id","dataset","status","files_found","created_ts"],"title":"BatchRow","description":"A source-sync batch (Batches list / detail)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/intake/batches/{batch_id}/process":{"post":{"tags":["Intake"],"summary":"Process Intake Batch","operationId":"process_intake_batch_v1__workspace_id__intake_batches__batch_id__process_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Batch Id"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRow"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Materialize Intake

> 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\`\`.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"MaterializeRequest":{"properties":{"dataset":{"anyOf":[{"$ref":"#/components/schemas/_DatasetSlug"},{"type":"null"}]}},"type":"object","title":"MaterializeRequest"},"_DatasetSlug":{"type":"string","maxLength":63,"minLength":2,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$"},"MaterializeResponse":{"properties":{"run_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Run Id"}},"type":"object","title":"MaterializeResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/intake/materialize":{"post":{"tags":["Intake"],"summary":"Materialize Intake","description":"Trigger the intake → customer-data materializer for this workspace.\n\nFires the materializer Databricks job (run-now); it rescans the workspace's\ncurated intake files and (re)materializes each snapshot dataset into\n``customer_data_<env>.<workspace_id>.<dataset>``. Every write is an idempotent\nkeyed MERGE / full overwrite, so a re-click is safe. Optionally scope to one\n``dataset``; omit for all curated snapshot datasets. Returns ``202`` with the\njob ``run_id`` (``null`` when the job is not configured in this environment).\nSame auth gate as ``POST /batches/{batch_id}/process``.","operationId":"materialize_intake_v1__workspace_id__intake_materialize_post","requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/MaterializeRequest"},{"type":"null"}],"title":"Body"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterializeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Update Intake Dataset

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"DatasetUpdateRunResponse":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"dataset":{"type":"string","title":"Dataset"},"status":{"$ref":"#/components/schemas/_DatasetUpdateStatus"},"source_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Source Ids"},"batch_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Batch Ids"},"materialize_run_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Materialize Run Id"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"}},"type":"object","required":["run_id","dataset","status","source_ids","batch_ids","created_at","updated_at"],"title":"DatasetUpdateRunResponse","description":"Durable status for one dataset update action."},"_DatasetUpdateStatus":{"type":"string","enum":["checking_drive","preparing","publishing","completed","needs_review","failed"]},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/intake/datasets/{dataset}/update":{"post":{"tags":["Intake"],"summary":"Update Intake Dataset","description":"Run the customer-facing dataset update flow.\n\nThis is the one-click orchestration path for the console: check mapped Drive\nfolders, prepare any newly landed files, and publish immediately when no\npreparation is needed. If preparation is async, the run remains durable and\nis advanced by file write-backs or by refresh.","operationId":"update_intake_dataset_v1__workspace_id__intake_datasets__dataset__update_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"dataset","in":"path","required":true,"schema":{"type":"string","minLength":2,"maxLength":63,"pattern":"^[a-z0-9][a-z0-9_-]*[a-z0-9]$","title":"Dataset"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetUpdateRunResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## GET /v1/{workspace\_id}/intake/update-runs/{run\_id}

> Get Intake Update Run

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"DatasetUpdateRunResponse":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id"},"dataset":{"type":"string","title":"Dataset"},"status":{"$ref":"#/components/schemas/_DatasetUpdateStatus"},"source_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Source Ids"},"batch_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Batch Ids"},"materialize_run_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Materialize Run Id"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"created_at":{"type":"string","title":"Created At"},"updated_at":{"type":"string","title":"Updated At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"}},"type":"object","required":["run_id","dataset","status","source_ids","batch_ids","created_at","updated_at"],"title":"DatasetUpdateRunResponse","description":"Durable status for one dataset update action."},"_DatasetUpdateStatus":{"type":"string","enum":["checking_drive","preparing","publishing","completed","needs_review","failed"]},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/intake/update-runs/{run_id}":{"get":{"tags":["Intake"],"summary":"Get Intake Update Run","operationId":"get_intake_update_run_v1__workspace_id__intake_update_runs__run_id__get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetUpdateRunResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## List Intake Materializations

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"PaginatedResponse_MaterializationRow_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/MaterializationRow"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"}},"type":"object","required":["items","has_more"],"title":"PaginatedResponse[MaterializationRow]"},"MaterializationRow":{"properties":{"dataset":{"type":"string","title":"Dataset"},"ingestion_mode":{"type":"string","title":"Ingestion Mode"},"status":{"type":"string","enum":["materialized","not_materialized"],"title":"Status"},"row_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Row Count"},"last_materialized_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Materialized At"}},"type":"object","required":["dataset","ingestion_mode","status"],"title":"MaterializationRow","description":"Per-dataset status of the customer-data destination table\n(``customer_data_<env>.<workspace_id>.<dataset>``)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/intake/materializations":{"get":{"tags":["Intake"],"summary":"List Intake Materializations","description":"Per-dataset materialization status for the workspace's Destinations tab.\n\nLists each registered dataset alongside its customer-data destination table's\nstatus — ``materialized`` (with row count + last-write time) or\n``not_materialized`` (no table yet). The dataset list + pagination mirror\n``GET /datasets`` (the contracts registry); the destination status is read\nfrom the ``customer_data_<env>`` catalog via the SQL warehouse. Member read.","operationId":"list_intake_materializations_v1__workspace_id__intake_materializations_get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Continuation Token"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","maxLength":64,"default":"name","title":"Sort By"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Search"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_MaterializationRow_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Write Back Intake File Status

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://platform.api-us.concurrence.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"StatusWriteBackRequest":{"properties":{"status":{"$ref":"#/components/schemas/_FileStatus"},"error_reason":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Error Reason"},"curated_path":{"anyOf":[{"$ref":"#/components/schemas/_VolumePath"},{"type":"null"}]},"cdc_path":{"anyOf":[{"$ref":"#/components/schemas/_VolumePath"},{"type":"null"}]}},"type":"object","required":["status"],"title":"StatusWriteBackRequest","description":"Status advance written by the async CDC job (P4).\n\nThe job posts the terminal verdict after conform/validate/diff. ``error_reason``\nmust be PHI-safe (the engine reports column + type + counts only — never cell\nvalues). ``curated_path``/``cdc_path`` are set only on a clean verdict."},"_FileStatus":{"type":"string","enum":["received","scanned","processing","curated","rejected","failed","held"]},"_VolumePath":{"type":"string","maxLength":1024,"minLength":1,"pattern":"^[A-Za-z0-9/._-]+$"},"IntakeFileRow":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"file_id — used for download."},"filename":{"type":"string","title":"Filename"},"dataset":{"type":"string","title":"Dataset","description":"Schema slug (UI label \"Schema\")."},"schema_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Schema Version","description":"The contract version this file validated against (e.g. ``v1``)."},"status":{"$ref":"#/components/schemas/_FileStatus"},"error_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Reason","description":"Null unless rejected/failed."},"size_bytes":{"type":"integer","title":"Size Bytes"},"ingested_at":{"type":"string","title":"Ingested At","description":"ISO-8601 timestamp the file was received."},"document_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Document Id","description":"The document this version belongs to (§5.9). Null for snapshot/CSV rows;\nset for documents — the console groups versions by it and the version chain."},"version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Version","description":"The file's version number (per-document for documents, per-dataset for\nsnapshot). Lets the UI render a document's version history."},"source_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Type","description":"Origin of the document this version belongs to — ``manual`` for console\nuploads, ``google_shared_drive`` for the Drive connector (V269). Null for\nsnapshot/CSV rows."},"source_file_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source File Id","description":"The source's stable external id (e.g. the Google Drive file id) for the\ndocument. Lets the console show provenance and confirm a re-synced file\nbumped the *same* document. Null for manual uploads and snapshot rows."},"source_folder_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Folder Path","description":"Where the file lived within the mapped Drive folder tree (V279) — the\nrelative path, folder names joined by ``/`` (e.g. ``clinical/notes``); ``''``\nat the mapped root. Lets the console show the original folder structure. Null\nfor manual uploads and snapshot rows."}},"type":"object","required":["id","filename","dataset","status","size_bytes","ingested_at"],"title":"IntakeFileRow","description":"A file in the Files list (intake-ui-mvp-design.md §5.1)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/intake/files/{file_id}/status":{"post":{"tags":["Intake"],"summary":"Write Back Intake File Status","description":"Advance a file's status from the async CDC/extraction job (P4).\n\nThe job authenticates with the workspace's API key (Bearer) over the\nstandard Databricks→platform-api path — so RLS scopes the update to\nthat workspace. Moves the row to its terminal verdict and records the\ncurated/cdc paths. For a batch-sourced file, advances its batch (chain the\nnext snapshot version + roll up) once the verdict is terminal.","operationId":"write_back_intake_file_status_v1__workspace_id__intake_files__file_id__status_post","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"file_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"File Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusWriteBackRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntakeFileRow"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.concurrence.com/api-reference/readme/platform/intake.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.