PlynxDocs

OpenAPI 3.1

Plynx Public API

v2026.04

Public REST surface for the Plynx IoT + maker platform.

Full description
Hand-written OpenAPI 3.1 spec covering the public HTTP endpoints exposed by
the Plynx gobackend. Three interfaces (REST, gRPC, MCP) share the same
domain services; this document is the authoritative contract for REST.

Auth modes:
  - sessionCookie: HTTP-only cookie set by POST /api/auth/login or
    /api/auth/register. Also accepted as `?token=<sessionID>` or as
    `Authorization: Bearer <sessionID>` on /api/auth/*.
  - bearerMCP: `Authorization: Bearer plnx_...` for /api/mcp/* and
    /api/ha/*. Key is issued by POST /api/mcp/keys.
  - bearerHA: alias for the MCP key scheme, used by the Home Assistant
    native REST bridge.

Error envelope is always `{ "error": "human-readable message" }`.

Endpoints

57

Tags

13

Schemas

21

Servers

  • https://plynx.cc — Production
  • http://127.0.0.1:8787 — Local dev

Downloads

openapi.jsonopenapi.yaml

Security schemes

  • sessionCookie (apiKey) — HTTP-only session cookie. Also accepts ?token= or Authorization Bearer for /api/auth/*.
  • bearerMCP (http) — MCP agent key, issued by POST /api/mcp/keys.
  • bearerHA (http) — Home Assistant REST-bridge token; reuses the MCP key scheme.

auth

Sessions, registration, password management.

post/api/auth/login+

Log in with email + password

Responses

  • 200 — OK. Session cookie set; token also in body.
  • 400
  • 401
post/api/auth/logout+

Invalidate the current session

Auth

sessionCookie

Responses

  • 200 — Session cleared.
post/api/auth/password-change+

Rotate the account password

Auth

sessionCookie

Responses

  • 200 — Password rotated.
  • 400
  • 401
post/api/auth/register+

Create a new account

Responses

  • 201 — Account created. Session cookie set; token also in body.
  • 400
  • 409
get/api/auth/session+

Inspect the current session

Auth

sessionCookie

Responses

  • 200 — Either an authenticated envelope or { user: null }.

projects

Dashboards, widgets, firmware, wiring, PCB, case.

get/api/projects+

List owner's projects

Auth

sessionCookie

Responses

  • 200 — OK
post/api/projects+

Create a new project

Auth

sessionCookie

Responses

  • 201 — Project created.
delete/api/projects/{id}+

Delete a project

Auth

sessionCookie

Responses

  • 200 — Deleted.
get/api/projects/{id}+

Fetch one project

Auth

sessionCookie

Responses

  • 200 — OK
  • 404
patch/api/projects/{id}+

Update project fields

Auth

sessionCookie

Responses

  • 200 — OK
get/api/projects/{id}/boards+

List boards attached to a project

Auth

sessionCookie

Responses

  • 200 — OK
delete/api/projects/{id}/boards/{boardId}+

Detach a board from this project (idempotent)

Auth

sessionCookie

Responses

  • 200 — OK
post/api/projects/{id}/boards/{boardId}+

Attach a board to this project (idempotent)

Auth

sessionCookie

Responses

  • 200 — OK
get/api/projects/{id}/case+

Read the 3D-case document

Auth

sessionCookie

Responses

  • 200 — OK
put/api/projects/{id}/case+

Save the 3D-case document

Auth

sessionCookie

Responses

  • 200 — OK
get/api/projects/{id}/collaborators+

List collaborators

Auth

sessionCookie

Responses

  • 200 — OK
post/api/projects/{id}/collaborators+

Invite a collaborator

Auth

sessionCookie

Responses

  • 201 — Added
get/api/projects/{id}/firmware+

Read the saved firmware source for CodeStudio

Auth

sessionCookie

Responses

  • 200 — OK
  • 404
put/api/projects/{id}/firmware+

Save firmware source

Auth

sessionCookie

Responses

  • 200 — OK
get/api/projects/{id}/pcb+

Read the PCB design

Auth

sessionCookie

Responses

  • 200 — OK
put/api/projects/{id}/pcb+

Save the PCB design

Auth

sessionCookie

Responses

  • 200 — OK
get/api/projects/{id}/widgets+

List persisted widgets for a project

Auth

sessionCookie

Responses

  • 200 — OK
put/api/projects/{id}/widgets+

Replace the widget set

Auth

sessionCookie

Responses

  • 200 — OK
get/api/projects/{id}/wiring+

Read the wiring diagram JSON

Auth

sessionCookie

Responses

  • 200 — OK
put/api/projects/{id}/wiring+

Save the wiring diagram

Auth

sessionCookie

Responses

  • 200 — OK

boards

Physical devices paired to projects.

get/api/boards+

List owner's boards

Auth

sessionCookie

Responses

  • 200 — OK
post/api/boards+

Create a new board

Auth

sessionCookie

Responses

  • 201 — Created; device token returned once.

pins

Virtual pin reads/writes.

put/api/boards/{id}/pins/{pinIndex}+

Write a virtual pin value

Auth

sessionCookie

Responses

  • 200 — Updated; broadcasts on the pin WebSocket.
get/api/projects/{id}/pins+

REST snapshot of project V-pin values

Returns the authoritative V-pin map for a project. For live updates subscribe to the WebSocket at `/ws/projects/{id}/collab` or `/ws/boards/{boardId}/pins`.

Auth

sessionCookie

Responses

  • 200 — OK

marketplace

Creator listings, purchases, reviews.

get/api/marketplace/listings+

List caller's creator listings

Auth

sessionCookie

Responses

  • 200 — OK
post/api/marketplace/listings+

Draft a new listing

Auth

sessionCookie

Responses

  • 201 — Created
get/api/marketplace/listings/{id}+

Fetch one listing (by id)

Auth

sessionCookie

Responses

  • 200 — OK
patch/api/marketplace/listings/{id}+

Edit draft listing fields

Auth

sessionCookie

Responses

  • 200 — OK
get/api/marketplace/listings/{id}/reviews+

List reviews for a listing

Responses

  • 200 — OK
post/api/marketplace/listings/{id}/reviews+

Leave a review for a listing

Auth

sessionCookie

Responses

  • 201 — Created

me

Current-user inbox, purchases, referral.

get/api/me/notifications+

Inbox of notifications for the current user

Auth

sessionCookie

Parameters

  • limit (query)

Responses

  • 200 — OK
get/api/me/purchases+

List my purchases

Auth

sessionCookie

Responses

  • 200 — OK
get/api/me/referral+

Get/lazily-create the caller's referral code

Auth

sessionCookie

Responses

  • 200 — OK

public

Unauthenticated discovery surface.

get/api/public/projects/feed+

Public feed of published projects

Parameters

  • sort (query)
  • limit (query)

Responses

  • 200 — OK
get/api/public/users/{username}+

Public profile for a user

Responses

  • 200 — OK
  • 404
get/api/public/users/{username}/listings+

Public marketplace listings for a user

Responses

  • 200 — OK

classrooms

PlynxEdu teacher/student roster + assignments.

get/api/assignments/{aid}/submissions+

List submissions for an assignment (teacher only)

Auth

sessionCookie

Responses

  • 200 — OK
post/api/assignments/{aid}/submissions+

Submit work against an assignment (student only)

Auth

sessionCookie

Responses

  • 201 — Created
get/api/classrooms+

List the caller's classrooms

Auth

sessionCookie

Responses

  • 200 — OK
post/api/classrooms+

Create a classroom

Auth

sessionCookie

Responses

  • 201 — Created
get/api/classrooms/{id}+

Read a classroom roster

Auth

sessionCookie

Responses

  • 200 — OK
get/api/classrooms/{id}/assignments+

List assignments in a classroom

Auth

sessionCookie

Responses

  • 200 — OK
post/api/classrooms/{id}/assignments+

Author an assignment (teacher only)

Auth

sessionCookie

Responses

  • 201 — Created

certificates

Public certificate verifier.

get/api/certificates/{id}+

Public certificate verifier

Responses

  • 200 — OK
  • 404

mcp

Model Context Protocol agent RPC.

post/api/mcp/rpc+

JSON-RPC 2.0 MCP entrypoint

Tools: `plynx_list_boards`, `plynx_read_pin`, `plynx_write_pin`, `plynx_push_ota`, `plynx_list_projects`. Scope-gated against the MCP key. See `/docs/mcp` for the full method catalog and protocol notes.

Auth

bearerMCP

Responses

  • 200 — JSON-RPC envelope.

ha

Home Assistant native REST bridge.

get/api/ha/board/{id}/pin/{pin}+

Read one virtual pin via the HA bridge

Auth

bearerHA

Responses

  • 200 — OK
post/api/ha/board/{id}/pin/{pin}+

Write one virtual pin via the HA bridge

Auth

bearerHA

Responses

  • 200 — OK
get/api/ha/boards+

Home Assistant board inventory

Auth

bearerHA

Responses

  • 200 — OK

workbench

AI copilot for the web workbench.

post/api/workbench/ai+

Conversational AI for the workbench right-rail

Auth

sessionCookie

Responses

  • 200 — AI reply.
post/api/workbench/ai-completions+

Inline editor completions

Auth

sessionCookie

Responses

  • 200 — Completion.

meta

get/api/openapi.json+

This OpenAPI spec as JSON

Responses

  • 200 — OpenAPI 3.1 document.
get/api/openapi.yaml+

This OpenAPI spec as YAML

Responses

  • 200 — OpenAPI 3.1 document.

Schemas

21 components defined. Download the spec above for the full field list.

AssignmentBoardCertificateClassroomDesignDocumentErrorFirmwareDocumentListingListingCreateInputMemberNotificationPersistedWidgetPinProjectPublicUserPurchaseReviewReviewAggregateRosterViewSessionEnvelopeSubmission