Artifacts API | DocuStore

Endpoints for document CRUD, file upload, metadata management, summarization, and permission control.

Artifacts represent documents in DocuStore (PDF, PowerPoint, or Word files). The artifacts API handles the full document lifecycle: upload, metadata extraction, summarization, sharing, and deletion.

List Artifacts

GET /artifacts?skip=0&limit=100&sort_by=updated_at&sort_order=-1

Returns all artifacts in the current workspace, filtered by the user's permissions. Supports pagination and sorting.

Parameter	Type	Default	Description
`skip`	integer	`0`	Number of results to skip
`limit`	integer	`100`	Maximum results to return
`sort_by`	string	`updated_at`	Sort field
`sort_order`	integer	`-1`	Sort direction (`-1` descending, `1` ascending)

Get Artifact

GET /artifacts/{artifact_id}

Returns a single artifact with its pages, metadata, and summary. Requires view permission.

Upload Document

POST /artifacts/upload
Content-Type: multipart/form-data

Uploads a file to blob storage and creates an artifact. This is the primary entry point for document ingestion. The upload triggers the full processing pipeline automatically. Requires the artifacts:create workspace action.

curl -X POST http://localhost:8000/artifacts/upload \
  -H "Authorization: Bearer <idp_token>" -H "X-Authz-Token: <authz_token>" \
  -F "file=@paper.pdf" \
  -F "artifact_type=RESEARCH_ARTICLE"

Field	Type	Required	Description
`file`	file	Yes	The document file (PDF, PPT/PPTX, or DOC/DOCX)
`artifact_type`	string	Yes	One of `SCIENTIFIC_PRESENTATION`, `RESEARCH_ARTICLE`, `SCIENTIFIC_DOCUMENT`, `DISCLOSURE_DOCUMENT`, `MINUTE_OF_MEETING`, `UNCLASSIFIED`
`source_uri`	string	No	Original source URL
`visibility`	string	No	`workspace` (default) or `private`

Response: 201 Created with the created ArtifactResponse.

After upload, the pipeline worker detects the Artifact.Created event and starts:

Document parsing (Docling) and page creation
Text extraction per page
Compound extraction, NER, embedding, and summarization (cascading)

Create Artifact (Metadata Only)

POST /artifacts/
Content-Type: application/json

Creates an artifact record without uploading a file. Useful when the file is already in blob storage. Requires the artifacts:create workspace action.

{
  "artifact_type": "RESEARCH_ARTICLE",
  "mime_type": "application/pdf",
  "source_filename": "paper.pdf",
  "storage_location": "artifacts/abc123/paper.pdf"
}

artifact_type, mime_type, and storage_location are required. source_uri and artifact_id are optional.

Update Metadata

Title, Date, Tags, and Authors

PATCH /artifacts/{artifact_id}/metadata
Content-Type: application/json

{
  "title": "NadD Inhibitor Screening Results",
  "presentation_date": "2026-03-29",
  "tags": [
    {"tag": "NadD", "entity_type": "target"},
    {"tag": "tuberculosis", "entity_type": "disease"}
  ],
  "authors": ["J. Smith", "A. Lee"]
}

A human correction that is recorded with provenance (who corrected it and when). Fields left out of the body are untouched; an explicit null clears the field. Unknown fields are rejected. Requires the artifacts:hiledit workspace action and edit permission on the artifact.

Summary

PATCH /artifacts/{artifact_id}/summary_candidate
Content-Type: application/json

{
  "summary": "This paper presents IC50 data for...",
  "model_name": "manual",
  "is_locked": true
}

Setting is_locked: true prevents automated re-summarization from overwriting the value.

Trigger Workflows

Summarization

POST /artifacts/{artifact_id}/summarize

Returns 202 Accepted. Starts the sliding-window artifact summarization workflow. Skips the "all pages done" precondition, useful for re-running after partial ingestion.

Metadata Extraction

POST /artifacts/{artifact_id}/extract-metadata

Returns 202 Accepted. Starts GLiNER2 + LLM extraction for title, authors, and date from the first page.

Get Summary

GET /artifacts/{artifact_id}/summary

Returns the current summary with metadata:

{
  "entity_id": "...",
  "summary": "This paper presents...",
  "model_name": "gemma3:27b",
  "date_extracted": "2026-03-29T12:00:00",
  "is_locked": false,
  "hil_correction": null
}

Get Workflow Statuses

GET /artifacts/{artifact_id}/workflows

Proxies to Temporal to return the current status of all workflows associated with the artifact (processing, summarization, metadata extraction).

Stream PDF

GET /artifacts/{artifact_id}/pdf

Returns the raw PDF binary from blob storage as application/pdf.

Stream Page Image

GET /artifacts/{artifact_id}/pages/{page_index}/image?size=thumb

Returns the rendered page image. Pass ?size=thumb for a lightweight JPEG thumbnail suitable for list views.

Permissions

View ACL

GET /artifacts/{artifact_id}/permissions

Returns the permission ACL with resolved user profiles.

POST /artifacts/{artifact_id}/shares

{
  "grantee_type": "user",
  "grantee_id": "user-uuid",
  "permission": "view"
}

DELETE /artifacts/{artifact_id}/shares

Same body as share. Only the owner or a workspace admin can share/revoke.

Update Visibility

PATCH /artifacts/{artifact_id}/visibility

{"visibility": "private"}

Delete Artifact

DELETE /artifacts/{artifact_id}

Returns 204 No Content. Deletes the artifact and all associated pages. Requires the artifacts:delete action (admins and owners bypass it) and edit permission on the artifact.