Artifacts API

Store and retrieve artifacts, files and generated content, and search them by meaning.

Base path: /api/v1/artifacts · Permission resource: artifact. All requests require authentication.

Endpoints

Method	Path	Purpose	Permission
POST	`/artifacts/upload`	Upload a file (multipart)	`artifact:create`
POST	`/artifacts/batch`	Batch / ZIP upload	`artifact:create`
POST	`/artifacts/`	Create from inline JSON content	`artifact:create`
GET	`/artifacts/`	List artifacts	`artifact:read`
GET	`/artifacts/{id}`	Get one artifact	`artifact:read`
GET	`/artifacts/{id}/download`	Download the bytes	`artifact:read`
POST	`/artifacts/{id}/link`	Attach to a target	`artifact:update`
DELETE	`/artifacts/{id}/link`	Detach from a target	`artifact:update`
DELETE	`/artifacts/{id}`	Delete	`artifact:delete`
POST	`/artifacts/{id}/retry`	Reprocess (re-index)	`artifact:update`
POST	`/artifacts/search`	Semantic search	`artifact:read`

Upload a file

POST /artifacts/upload uses multipart form data with fields file, target_type, target_id, context and visibility:

curl -s -X POST "http://localhost:8000/api/v1/artifacts/upload" \
  -H "Authorization: Bearer $CLOUDPEEK_TOKEN" \
  -F "file=@/path/to/evidence.log" \
  -F "target_type=incident" \
  -F "target_id=101" \
  -F "context=VPN logs for incident 101"

POST /artifacts/batch accepts a ZIP/project upload for many files at once.

Create from inline content

POST /artifacts/ creates an artifact from content you provide in JSON, useful for saving generated text:

Field	Type	Notes
`filename`	string	1-500 chars
`content`	string	the content (up to ~5M chars)
`mime_type`	string	default `text/plain`
`is_base64`	bool	default `false`
`source`	string	default `agent`
`target_type` / `target_id`	string	both or neither: what to attach to
`context`	string	≤500 chars
`visibility`	string	default `scoped`

Semantic search

POST /artifacts/search finds artifacts by meaning, not just keywords:

Field	Type	Notes
`query`	string	the natural-language query
`target_type` / `target_id`	string	optionally restrict to a target
`limit`	int	1-100, default 10
`context_window`	int	0-5, surrounding chunks to include

curl -s -X POST "http://localhost:8000/api/v1/artifacts/search" \
  -H "Authorization: Bearer $CLOUDPEEK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "query": "failed VPN logins from overseas", "limit": 5 }'

Linking

Attach an artifact to an incident or investigation with POST /artifacts/{id}/link (body { "target_type": "incident", "target_id": "101", "context": "…" }), and detach with the matching DELETE.

The artifact object

Includes: id, tenant_id, uploaded_by_id, original_filename, mime_type, file_size_bytes, content_hash, source, visibility, status, vector_status, vector_chunk_count, graph_status, attachments, created_at, updated_at. The vector_status and graph_status fields show indexing progress that powers semantic search and the knowledge graph.

Artifacts: the UI and concepts.
Investigations API: list artifacts produced by an investigation.