Developer API

The Locus Developer API lets local Unreal Editor tools work with Locus Notes, Documents, and Pins. It is intended for C++ editor plugins, Editor Utility Blueprints and Widgets, Unreal Python scripts, and Editor-hosted pipeline automation.

Your Editor tool
       ↓
Locus Developer API
       ↓
Existing Locus application

Developer operations use the same validation, revisions, persistence, conflict protection, Document path rules, Source Control routing, and application lifetime as the Locus UI. Use the API instead of directly editing Locus files.

Choose an API

Surface	Best for	Start here
Native C++	Editor plugins, native tools, advanced integrations	C++ Developer API
Blueprint	Editor Utility Blueprints, Editor Utility Widgets	Blueprint Developer API
Unreal Python	Editor scripts, validation, batch and unattended automation	Python Developer API

MCP Integration is the separate AI/agent-facing external-client surface. C++, Blueprint, and Python Developer tools do not use MCP internally.

Engine compatibility

Core Locus, C++, Blueprint, and MCP are supported on Unreal Engine 5.4–5.8. The interactive and unattended Python Developer API requires Unreal Engine 5.6 or newer.

Surface	UE 5.4–5.5	UE 5.6–5.8
C++	Supported	Supported
Blueprint	Supported	Supported
Python	Not supported	Supported
MCP	Supported	Supported

Current operation surface

On their supported Engine versions, all 16 curated operations are available from C++, Blueprint, and Python:

Content	Operations
Notes	List, Get, Search, Create, Update, Archive
Documents	List, Get, Search, Create, Update
Pins	List, Get, Create, Update metadata, Add comment

The API intentionally does not expose Note folder mutation; Document rename, move, or delete; Pin position mutation or full anchor replacement; Pin view/surface manipulation; Automation capability negotiation or change events; or request deadlines.

Identities

Note: GUID plus explicit Shared or Private scope.
Pin: GUID plus explicit Shared or Private scope.
Document: normalized Markdown path relative to ProjectDocuments.

A Document’s presentation root, presentation path, /Game/... context, and absolute filesystem location are not alternative identities.

Document presentation roots

Create requests select one concrete root. The supplied path is relative to that visible root:

Presentation root	Supplied path	Authoritative identity
Locus Documents	`Design/Combat.md`	`Design/Combat.md`
Content Browser	`Characters/Hero.md`	`Content/Characters/Hero.md`

Do not prepend Content/ when creating beneath Content Browser. Locus applies that mapping once.

Revisions

Reads and successful mutations return an opaque revision. An update or archive must submit the current value as ExpectedRevision:

Get → Snapshot + Revision → Update with ExpectedRevision

Do not parse or manufacture revisions. If the result is StaleRevision, read the authoritative item again and reconsider the change. Locus does not hide a stale write with an automatic reread or retry.

Errors

Branch on the typed error code, not the human-readable message:

InvalidInput, NotFound, AlreadyExists, Conflict, StaleRevision, AccessDenied, Unsupported, Busy, Cancelled, Unavailable, ShuttingDown, and OperationFailed. None represents no error.

A retryable Unavailable query can be resubmitted on a later normal Editor tick. Do not block the Game Thread while waiting.

Success and Source Control status are separate

A successful local mutation can report local persistence as Committed while Source Control is Pending, NotConfigured, Unknown, or NotRequired. That is still a successful Locus operation. Operation status is provider-neutral additional information for the user’s normal Source Control workflow.

Locus does not submit changes or administer changelists.

Trust boundary

C++, Blueprint, and Python are trusted local Editor tooling. A caller that explicitly requests Private scope intentionally accesses the current project’s local Private content. MCP’s Allow Changes and Allow Private Notes and Pins settings govern the separate external-client MCP boundary and do not govern an in-process Developer API caller.