REST API Reference

All endpoints live under /api/v1/. Every error response uses the same envelope:

{ "error": { "code": "STRING_CODE", "message": "Human readable message", "details": {} } }

The full, spec-source-of-truth version of this document lives at specs/001-datacore-knowledge-warehouse/contracts/rest-api.md.

Resources

Method & Path	Description
GET /resources?q=	List resources, optionally filtered by name substring
POST /resources	Register a resource: { name, type, source: { kind: "UPLOAD", file } | { kind: "URL", url } }
GET /resources/{id}	Get one resource, including artifacts[], derived no_matching_pipeline, and source_type/source_uri (source_uri is only populated for URL sources — an UPLOAD's path is a private s3:// reference, never exposed)
GET /resources/{id}/artifacts/{artifactId}	Fetch an artifact's actual content (text, JSON, or vector) — not just its pointer
PATCH /resources/{id}	Edit metadata, e.g. { name }
POST /resources/{id}/reprocess	Re-run the pipeline from step 0; overwrites existing artifacts in place
PUT /resources/{id}/toggle	Flip is_enabled — gates whether an (future) MCP server exposes this resource to an LLM; pipeline processing is unaffected either way
DELETE /resources/{id}	Delete a resource and cascade-clean its artifacts; rejected with 409 while PROCESSING

Pipelines

Method & Path	Description
GET /pipelines	List pipelines with their ordered steps
POST /pipelines	Create: { name, trigger_type, steps: [{ plugin_id, max_attempts?, backoff_seconds?, timeout_seconds? }] } — 409 if the trigger type already has a pipeline
PUT /pipelines/{id}	Replace the step sequence; in-flight resources are unaffected
DELETE /pipelines/{id}	Delete; in-flight resources are unaffected (they run from their own captured step snapshot)

Plugins

Method & Path	Description
GET /plugins	List all registered plugins
PUT /plugins/{id}/toggle	Toggle active/inactive
DELETE /plugins/{id}	Delete; 409 PLUGIN_IN_USE if referenced by a pipeline step

Internal callback (Plugin Workers → Core)

Method & Path	Description
POST /internal/artifacts/{resource_id}	Called by a plugin worker to report success (with an artifact) or failure for its step — see Building a Plugin

Viewing an artifact's content

GET /resources/{id}/artifacts/{artifactId} is what powers the "view result" click on an artifact chip in the Web UI. Core fetches the content server-side (never proxying raw storage credentials to the browser):

curl http://localhost:3010/api/v1/resources/<id>/artifacts/<artifactId>

{
  "id": "...",
  "type": "REPO_ANALYSIS",
  "content_type": "json",
  "content": { "username": "octocat", "repo_count": 8, "repos": [ /* ... */ ] }
}