Artifacts API | DocuStore

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

Artifacts represent documents in DocuStore (typically PDFs). 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.

Field	Type	Required	Description
`file`	file	Yes	The document file (PDF)
`artifact_type`	string	Yes	Document type (e.g., `pdf`)
`source_uri`	string	No	Original source URL
`visibility`	string	No	`workspace` (default), `private`, or `shared`

Response: 201 Created with the created ArtifactResponse.

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

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

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

Update Metadata

Title

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

{
  "title": "NadD Inhibitor Screening Results",
  "model_name": "manual",
  "date_extracted": "2026-03-29T00:00:00Z"
}

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