Data Intake

Customer Data Intake endpoint for streaming HMAC-authenticated PHI file uploads into a workspace's landing zone.

The Data Intake endpoint accepts streaming, HMAC-authenticated file uploads from approved customer integrations. Bytes are streamed into workspace storage, recorded in an auditable upload log, and emitted as a signal event that downstream pipelines can subscribe to.

Conceptual overview. For when to use intake versus connectors, compliance posture, and downstream projection behavior, see Customer Data Intake in the conceptual docs.

Requires provisioning. Intake requires a per-customer slug and HMAC secret to be provisioned by Amigo before the endpoint will accept uploads. Coordinate with your solutions contact for onboarding.

Upload a File

POST /v1/{workspace_id}/intake/files

Streams a single file into the workspace landing zone. The request body is the raw file bytes; all metadata travels via headers so large payloads do not need to be buffered into JSON.

Authentication

Two authentication layers stack on every upload:

1. Platform API key or JWT: standard platform-api authentication, scoped to {workspace_id}.

2. HMAC signature: SHA-256 HMAC over a canonical request string, keyed by the per-customer secret. The canonical string is a colon-delimited concatenation of sha256:content_type:customer_slug:timestamp. The signature is sent hex-encoded in the x-amigo-intake-signature header.

The x-amigo-intake-timestamp header is a Unix seconds value; requests outside a short freshness window (default: 5 minutes) are rejected with 401 to prevent replay.

Headers

Header	Required	Description
x-amigo-intake-sha256	yes	Lowercase hex SHA-256 of the file body (64 chars). The server recomputes this while streaming and rejects on mismatch.
x-amigo-intake-timestamp	yes	Unix seconds when the signature was produced. Must be within the freshness window.
x-amigo-intake-signature	yes	Lowercase hex SHA-256 HMAC of the canonical string, keyed by the customer's intake secret.
x-amigo-intake-customer-slug	yes	Customer identifier. Must match ^[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$.
x-amigo-intake-filename	yes	Original filename. Max 256 chars; no slashes or null bytes.
x-amigo-intake-content-type	no	Media type of the payload. Defaults to application/octet-stream.

Request Body

Raw file bytes. Streamed; no size limit enforced at the application layer beyond the platform's standard request limits.

Response

201 Created

Field	Type	Description
id	string (UUID)	Upload identifier. Matches the row in the intake audit log.
volume_path	string	Storage path the bytes were written to. Namespace-scoped to the customer.
sha256	string	Server-computed SHA-256 over the bytes that actually arrived. Equal to the supplied header on success.
size_bytes	integer	Total bytes received.
duplicate_of	object or null	If the uploaded file is a content-level duplicate of a previous upload in the same workspace, contains id (string) and received_at (ISO 8601 timestamp) of the original upload. null if no duplicate was found.
scan_status	string	Malware scan state: skipped, pending, clean, or infected.

Error Responses

Status	Meaning
401 Unauthorized	API key missing, HMAC signature invalid, timestamp stale, or a required header malformed.
404 Not Found	Workspace or customer slug not known to intake.
422 Unprocessable Entity	Client-supplied SHA-256 did not match what actually arrived; the partial object has been deleted.
503 Service Unavailable	Intake is not configured for this deployment.

Canonical Signing String

The HMAC input is constructed as:

{sha256}:{content_type}:{customer_slug}:{timestamp}

Example (values shown for illustration):

a3b4...ef:application/pdf:acme-health:1744819200

The signing key is the customer-specific intake secret provisioned out-of-band.

Example

BODY_SHA=$(sha256sum referral.pdf | cut -d' ' -f1)
TS=$(date +%s)
CT="application/pdf"
SLUG="acme-health"
MSG="${BODY_SHA}:${CT}:${SLUG}:${TS}"
SIG=$(printf "%s" "$MSG" | openssl dgst -sha256 -hmac "$INTAKE_SECRET" -hex | cut -d' ' -f2)

curl -X POST "https://api.amigo.ai/v1/${WORKSPACE_ID}/intake/files" \
  -H "Authorization: Bearer $API_KEY" \
  -H "x-amigo-intake-sha256: $BODY_SHA" \
  -H "x-amigo-intake-timestamp: $TS" \
  -H "x-amigo-intake-signature: $SIG" \
  -H "x-amigo-intake-customer-slug: $SLUG" \
  -H "x-amigo-intake-filename: referral.pdf" \
  -H "x-amigo-intake-content-type: $CT" \
  --data-binary @referral.pdf

Download an Uploaded File

GET /v1/{workspace_id}/intake/links/{link_id}/uploads/{upload_id}/download

Retrieves the raw file bytes for a previously uploaded file. Returns the file with Content-Disposition: attachment so browsers trigger a download.

Path Parameters

Parameter	Type	Description
link_id	UUID	Intake link that received the upload
upload_id	UUID	Upload identifier (from the upload list or the original upload response)

Response

200 OK with application/octet-stream body containing the raw file bytes.

Error Responses

Status	Meaning
404 Not Found	Link, upload, or underlying file not found
422 Unprocessable Entity	Invalid path parameter format
502 Bad Gateway	Storage backend failed to serve the file

Example

curl -o referral.pdf \
  "https://api.platform.amigo.ai/v1/${WORKSPACE_ID}/intake/links/${LINK_ID}/uploads/${UPLOAD_ID}/download" \
  -H "Authorization: Bearer $API_KEY"

Permissions

Scope	Grants
intake:write	Submit uploads to the workspace intake endpoint.
intake:read	Read the workspace intake audit log and download uploaded files.

The intake:write scope is not included in the default member role; it must be granted explicitly to the API key used by the upstream customer integration.

API Reference

• Data Intake