Developers Guide

This guide covers integrating with udServer programmatically — automating administration, driving it from your own tooling, or building an application against it.

APIs

• udServer API — the HTTP API. Everything the web interface does, it does through these endpoints: users and sessions, organisations and permissions, projects, scenes, files, work items, licensing, and server administration.
• WebSocket API — event-driven scene collaboration. Pushes scene edits and viewer presence as they happen instead of being polled.

Getting Started

Every HTTP endpoint lives under /api/ and returns a JSON object containing at least a success boolean; when it is false, a message field says why. The error message list at the top of the API reference covers the values common to every endpoint.

Authentication is by API key, supplied either as the apikey cookie or as an apikey field in the request body. Users create their own keys from Settings → API Keys — see Account Settings — and a key carries exactly the permissions of the user who created it, so a script can never do more than the person running it.

For an application logging a user in rather than acting as one, use the external session endpoints, which are the flow behind approving udStream and other udSDK applications.

Things Worth Knowing Early

• Permissions are per-project, not just per-organisation. A role can be scoped to specific projects, so a member's effective permissions differ from project to project within one organisation. See Permissions.
• Signed documents are byte-exact. Licenses and issuer check-ins are verified against the bytes as sent. Parsing and re-encoding the JSON — even without changing a value — invalidates the signature.
• Sequence cursors are not timestamps. Scene synchronisation uses a per-scene edit sequence. It is named lastupdate/nextupdate for historical reasons but must be treated as opaque, never compared against a clock.
• /api/sdk/* is not documented here. That namespace is the private udSDK communication channel.