REST API

PLUR Enterprise exposes a REST API at /api/v1/. It mirrors the MCP tools one-to-one with the same data model and the same permission enforcement. Use it for CI, automation, dashboards, mobile clients, and anything that doesn’t speak MCP.

The canonical OpenAPI 3 spec is served at:

https://your-server/api/v1/openapi.yaml

Generate clients with openapi-generator-cli, import into Postman, or read it directly.

Authentication

Every request needs an Authorization: Bearer <token> header. Tokens come from one of:

• OAuth/OIDC session — short-lived tokens issued after SSO login.
• API key — long-lived tokens issued from the admin dashboard for service-to-service traffic.
• SCIM-provisioned identity — for automated user provisioning.

Tokens scope to a single user; permission resolution happens server-side against the user’s group memberships. See Authentication and Permissions & scopes.

Engrams

Method	Path	Description
GET	/api/v1/engrams	List engrams in a scope (paginated).
POST	/api/v1/engrams	Create an engram.
GET	/api/v1/engrams/{id}	Retrieve.
PATCH	/api/v1/engrams/{id}	Update specific fields.
DELETE	/api/v1/engrams/{id}	Retire (soft delete).
POST	/api/v1/engrams/{id}/feedback	Submit positive/negative feedback.
POST	/api/v1/engrams/{id}/promote	Promote a candidate.
POST	/api/v1/engrams/{id}/pin	Pin (admin). Audited.

Example — create:

curl -X POST https://plur.your-org.com/api/v1/engrams \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "statement": "Deploys must run migrations first.",
    "type": "procedural",
    "scope": "group:platform",
    "domain": "software.deployment",
    "tags": ["deploy", "migrations"]
  }'

Search

Method	Path	Description
POST	/api/v1/recall	BM25 + embeddings + RRF.
POST	/api/v1/recall/bm25	BM25 only.
POST	/api/v1/inject	Inject relevant engrams for a task.

Example — inject:

curl -X POST https://plur.your-org.com/api/v1/inject \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Add a POST /users endpoint with validation.",
    "scope": "group:platform",
    "max_engrams": 10
  }'

Episodes

Method	Path	Description
GET	/api/v1/episodes	Query timeline (filters: from, to, agent, channel, session).
POST	/api/v1/episodes	Capture an episode.
GET	/api/v1/episodes/{id}	Retrieve.

Sessions

Method	Path	Description
POST	/api/v1/sessions	Start a session.
POST	/api/v1/sessions/{id}/end	End a session, attach learnings.
GET	/api/v1/sessions/{id}	Retrieve.

Packs

Method	Path	Description
GET	/api/v1/packs	List installed packs.
POST	/api/v1/packs	Install (multipart upload or URL).
DELETE	/api/v1/packs/{name}	Uninstall.
POST	/api/v1/packs/export	Export a scope as a pack.

Admin

These endpoints require admin role.

Method	Path	Description
GET	/api/v1/admin/users	List users.
POST	/api/v1/admin/users	Provision (or via SCIM).
GET	/api/v1/admin/groups	List groups.
POST	/api/v1/admin/groups/{id}/members	Add member.
GET	/api/v1/admin/api-keys	List API keys.
POST	/api/v1/admin/api-keys	Issue API key.
DELETE	/api/v1/admin/api-keys/{id}	Revoke.
GET	/api/v1/admin/audit	Query audit log.
GET	/api/v1/admin/insights	Quality metrics, engram health.

Webhooks

Method	Path	Description
GET	/api/v1/admin/webhooks	List webhooks.
POST	/api/v1/admin/webhooks	Register.
DELETE	/api/v1/admin/webhooks/{id}	Remove.
POST	/api/v1/admin/webhooks/{id}/test	Send a test event.

Delivery signing: every webhook POST carries X-PLUR-Signature: sha256=<hmac> computed over the raw body with the webhook’s secret. Verify before processing. See Webhooks.

SCIM 2.0

SCIM endpoints live at /scim/v2/ (separate root for protocol compliance):

Path	Description
/scim/v2/Users	User provisioning.
/scim/v2/Groups	Group provisioning.
/scim/v2/ServiceProviderConfig	SCIM capabilities.

SCIM bearer tokens are managed in the admin dashboard. See SCIM 2.0 provisioning.

Errors

Errors are RFC 7807 problem documents:

{
  "type":   "https://docs.plur.ai/errors/insufficient-permission",
  "title":  "Insufficient permission",
  "status": 403,
  "detail": "User does not have write access to scope group:platform.",
  "instance": "/api/v1/engrams"
}

Common statuses:

• 400 — validation error
• 401 — missing/invalid token
• 403 — token valid but insufficient scope
• 404 — not found (or hidden by permissions — same shape, by design)
• 409 — conflict (e.g., duplicate engram id, pack integrity mismatch)
• 429 — rate limit
• 500 — server error

Rate limits

Default: 600 req/min/token. Per-route caps for write-heavy endpoints (POST/PATCH) at 60 req/min/token. Configurable per-deployment. Rate-limit state surfaces in RateLimit-* response headers.

Versioning

v1 is the current contract. Breaking changes will bump to v2 with parallel hosting and a deprecation window. Additive changes (new fields, new endpoints) ship continuously without a version bump.