REST API for the Document Management domain — the central store for uploaded files and their metadata across all safety net programs.
Upload model: A document and its first version are created atomically via POST /documents (multipart/form-data). Subsequent versions are uploaded via POST /documents/{documentId}/document-versions. File content is delivered via GET /document-versions/{documentVersionId}/content (proxy by default; states may overlay to redirect).
Context passthrough: Callers attach correlation context to a document via metadata at creation or via PUT /documents/{documentId}/metadata/{domain} after the fact. Metadata is echoed in events so downstream consumers can correlate without additional lookups. Keys are structured as nested objects per domain namespace — { "intake": { "verificationId": "..." } }.
Document types: Baseline types are seeded from document-management-config.yaml. States add program-specific types at runtime via POST /document-types.
Status: Alpha — Breaking changes expected.
https://api.example.com/document-managementDocuments
Document records and file upload.
▶
GET
/documents
List documents
#
Retrieve a paginated list of documents. Filter by document type or subject via document links.
| Name | Type | In | Req | Description |
|---|---|---|---|---|
| ▶q | string | query | Search query using field:value syntax. Multiple conditions separated by | |
| limit | integer | query | Maximum number of items to return (1-100). |
|
| offset | integer | query | Number of items to skip before collecting results. |
|
| ▶sort | string | query | Comma-separated list of fields to sort the response by. Prefix a field | |
| documentTypeId | string | query | Filter by document type. |
|
| lifecycleState | ▶ DocumentLifecycleState | query | Filter by lifecycle state. |
▶
POST
/documents
Upload a document
#
Create a document and its first version atomically. The document is immediately active. Accepts multipart/form-data with the file bytes and document metadata in a single request.
If the adapter's virus scanner rejects the file, returns 422 with error code file_rejected_by_virus_scan and no document is created.
Pass metadata as a JSON string in the multipart body to attach correlation context at creation time (e.g. { "intake": { "verificationId": "ver-abc" } }).
▶
GET
/documents/{documentId}
Get a document
#
Retrieve a single document by identifier. Documents in destroyed state are returned with their metadata intact but file content is no longer accessible.
| Name | Type | In | Req | Description |
|---|---|---|---|---|
| documentId | string | path | ✓ | Unique identifier of the document. |
▶
PATCH
/documents/{documentId}
Update a document
#
Update mutable document fields. Metadata is not patchable here — use the namespace-level metadata endpoints instead.
| Name | Type | In | Req | Description |
|---|---|---|---|---|
| documentId | string | path | ✓ | Unique identifier of the document. |
▶
PUT
/documents/{documentId}/metadata/{domain}
Set domain metadata on a document
#
Replace the calling domain's entire metadata namespace on a document. Other domains' namespaces are unaffected. Used for context passthrough when metadata is not known at upload time.
| Name | Type | In | Req | Description |
|---|---|---|---|---|
| documentId | string | path | ✓ | Unique identifier of the document. |
| domain | enum | path | ✓ | The calling domain's namespace to set or remove. enum case-management client-management communication data-exchange document-management eligibility identity-access intake platform scheduling workflow |
▶
DELETE
/documents/{documentId}/metadata/{domain}
Remove domain metadata from a document
#
Remove the calling domain's entire metadata namespace from a document.
| Name | Type | In | Req | Description |
|---|---|---|---|---|
| documentId | string | path | ✓ | Unique identifier of the document. |
| domain | enum | path | ✓ | The calling domain's namespace to set or remove. enum case-management client-management communication data-exchange document-management eligibility identity-access intake platform scheduling workflow |
DocumentVersions
Immutable version history for documents.
▶
POST
/documents/{documentId}/document-versions
Upload a new version
#
Upload a subsequent version of an existing document. Creates an immutable DocumentVersion record and updates Document.latestVersionId. Each upload preserves prior versions so the file that was current at any point in time is recoverable (required by 7 CFR § 272.1 and 45 CFR § 164.312).
If the adapter's virus scanner rejects the file, returns 422 with error code file_rejected_by_virus_scan and no version is created.
| Name | Type | In | Req | Description |
|---|---|---|---|---|
| documentId | string | path | ✓ | Unique identifier of the document. |
▶
GET
/document-versions/{documentVersionId}
Get a document version
#
Retrieve metadata for a specific document version. Does not return file bytes — use the content endpoint for that.
| Name | Type | In | Req | Description |
|---|---|---|---|---|
| documentVersionId | string | path | ✓ | Unique identifier of the document version. |
▶
GET
/document-versions/{documentVersionId}/content
Get file content
#
Retrieve the file bytes for a document version. Emits a document_version.accessed audit event on every call (required by HIPAA 45 CFR § 164.312).
The baseline response is 200 with the file streamed as application/octet-stream (proxy delivery). States that prefer redirect delivery add x-content-delivery: redirect via overlay — the response then returns 302 to a time-limited signed storage URL. Both response shapes are documented here so clients handle either.
| Name | Type | In | Req | Description |
|---|---|---|---|---|
| documentVersionId | string | path | ✓ | Unique identifier of the document version. |
DocumentTypes
Document type catalog — retention rules and classification.
▶
GET
/document-types
List document types
#
Retrieve the catalog of document types. Includes both config-seeded (system) and runtime-created (user) types.
| Name | Type | In | Req | Description |
|---|---|---|---|---|
| ▶q | string | query | Search query using field:value syntax. Multiple conditions separated by | |
| limit | integer | query | Maximum number of items to return (1-100). |
|
| offset | integer | query | Number of items to skip before collecting results. |
|
| ▶sort | string | query | Comma-separated list of fields to sort the response by. Prefix a field |
▶
POST
/document-types
Create a document type
#
Create a state-defined document type. Runtime-created types are marked source: user and can be deleted via the API. Config-seeded types cannot be deleted.
▶
GET
/document-types/{documentTypeId}
Get a document type
#
Retrieve a single document type by identifier.
| Name | Type | In | Req | Description |
|---|---|---|---|---|
| documentTypeId | string | path | ✓ | Unique identifier of the document type. |
▶
DELETE
/document-types/{documentTypeId}
Delete a document type
#
Delete a user-created document type. Returns 409 if the type is config-seeded (source: system) or if documents of this type exist.
| Name | Type | In | Req | Description |
|---|---|---|---|---|
| documentTypeId | string | path | ✓ | Unique identifier of the document type. |
DocumentLinks
Associations between documents and program records (applications, cases, etc.).
▶
GET
/document-links
List document links
#
Retrieve document-subject associations. Filter by documentId or subjectId to find all documents for a subject or all subjects for a document.
| Name | Type | In | Req | Description |
|---|---|---|---|---|
| ▶q | string | query | Search query using field:value syntax. Multiple conditions separated by | |
| limit | integer | query | Maximum number of items to return (1-100). |
|
| offset | integer | query | Number of items to skip before collecting results. |
|
| ▶sort | string | query | Comma-separated list of fields to sort the response by. Prefix a field | |
| documentId | string | query | Filter by document. |
|
| subjectId | string | query | Filter by subject (application, case, etc.). |
|
| subjectType | string | query | Filter by subject type. |
▶
POST
/document-links
Link a document to a subject
#
Associate a document with a program record (application, case, etc.). Enables cross-program reuse — the same document can satisfy obligations for multiple programs without duplication.
▶
GET
/document-links/{documentLinkId}
Get a document link
#
Retrieve a single document-subject association by identifier.
| Name | Type | In | Req | Description |
|---|---|---|---|---|
| documentLinkId | string | path | ✓ | Unique identifier of the document link. |