Reference

REST API.

Mounted at /api/v1 on the local daemon. Resources are addressed by logical IDs, never absolute paths. Mutations require an idempotency key, a revision precondition, and — where policy says so — an approval bound to an exact preview.

Base and authentication

text

http://127.0.0.1:8765/api/v1

local browser:  intralock_session cookie (HTTP-only, SameSite)
programmatic:   Authorization: Bearer ilk_…
                scoped to actor + workspace + capabilities + expiry

Loopback binding is not authentication. The server checks Origin, session, capability, scope, and object version on every mutating request. A missing or invalid credential returns 401; a valid credential without the capability returns 403 without revealing whether the object exists.

Routes

Method & path	Purpose	Auth
GET /health	Daemon, catalog, watcher, extract health	none (local)
GET /api/v1/workspaces	List registered workspaces	session
POST /api/v1/workspaces	Register a directory	session + capability
GET /api/v1/workspaces/{id}	Workspace detail and freshness	session
GET /api/v1/objects/{id}	Object metadata, provenance, edges	session
GET /api/v1/objects/{id}/content	Authorized content, bounded range	session
GET /api/v1/search	Full-text search, permission-filtered	session
POST /api/v1/graph/query	Typed, bounded traversal	session
POST /api/v1/context/bundles	Budgeted context assembly	session
GET /api/v1/capabilities	Capability registry for the caller	session
POST /api/v1/tasks	Start durable async work	session + capability
GET /api/v1/tasks/{id}	Task state, progress, outcome	session
POST /api/v1/changes/preview	Three-way diff; no write	session + capability
POST /api/v1/changes/apply	Approved, versioned write	approval + capability
POST /api/v1/backups	Consistent backup	session + capability
GET /api/v1/audit	Ledger entries and receipts	session

Search

http

GET /api/v1/search?query=architecture&workspace_id=wks_01JEX&limit=10
Accept: application/json

{
  "results": [
    {
      "object_id": "obj_01J9F2",
      "version": "sha256:8b708e8a…",
      "title": "workspace-architecture.md",
      "kind": "document",
      "score": 0.82,
      "freshness": { "indexed_at": "2026-11-09T12:31:02Z", "lag_seconds": 12 },
      "provenance": "observed"
    }
  ],
  "next_cursor": "eyJvZmZzZXQiOjEwfQ"
}

The response never includes a hidden object, a hidden count, or an excluded path. If the catalog lags, lag_seconds is reported rather than silently presenting the result as current.

Writes: preview, then apply

http

POST /api/v1/changes/preview
Idempotency-Key: 0f3c2a9e-…
Content-Type: application/json

{
  "workspace_id": "wks_01JEX",
  "operation": "homepage.publish",
  "targets": ["obj_01J9F2"],
  "expected_versions": { "obj_01J9F2": "sha256:8b708e8a…" }
}

→ 200 with preview hash, diff, warnings
→ approval_id (if human approval required)

POST /changes/apply requires the approval bound to that preview hash. If any precondition changed, the approval is stale and the server returns 409 with conflict_version — it does not apply a partial write.

Problem details

json

{
  "code": "conflict",
  "message": "Object changed since preview.",
  "request_id": "req_01JEX7",
  "conflict_version": "sha256:9c1d…",
  "retry_after": null,
  "approval_request_id": null,
  "field_errors": []
}

Code	HTTP	Client action
validation_failed	400	Fix fields; re-read `field_errors`.
unauthorized	401	Re-authenticate; do not retry blindly.
forbidden	403	Request a narrower capability or stop.
not_found	404	Resolve by ID, not path.
conflict	409	Re-preview against the new version.
approval_required	428	Route to an authenticated human surface.
rate_limited	429	Honor `retry_after`.
unavailable	503	Daemon not ready; retry with backoff.

Contract rules

Writes require Idempotency-Key; a replay returns the prior receipt instead of applying again.
Writes use If-Match or an explicit expected version; a mismatch is a conflict, not a last-writer-wins.
Unknown fields are rejected on security-sensitive mutations; reads may be liberal where documented.
Breaking changes are versioned by route or media type, with a machine-readable compatibility table.
No direct source-file write endpoint exists before safe mutation and rollback are proven.

OpenAPI

yamlopenapi.json (excerpt)

openapi: 3.1.0
info:
  title: Intralock Local API
  version: 1.0.0
paths:
  /api/v1/search:
    get:
      operationId: searchWorkspace
      security: [{ localSession: [] }]
      parameters:
        - { name: query, in: query, required: true,
            schema: { type: string, minLength: 1 } }
        - { name: workspace_id, in: query, required: true,
            schema: { type: string } }
      responses:
        '200': { description: Permission-filtered results }
        '403': { description: Not authorized for this workspace }