Developer Documentation V1
Stop building APIs for simple communication. Use a vertex.
Node Vertex is a programmable signaling fabric where every URL is a stateful, secure, and optionally intelligent endpoint. Use it to store values, signal events, hand off files, connect agents, coordinate devices, and build automation without creating another small API service.
What is a vertex?
A vertex is an addressable endpoint owned by a tenant. It has a key, type, authentication policy, lifecycle, current value or payload, optional TTL, optional event history, and optional specialized behavior such as append-only, read-once, write-once, mailbox, file, or operation-result semantics.
https://n-v.io/{tenant}/{vertexKey}
https://n-v.io/acme/build-status
Create a vertex
Create vertices through the API or admin UI. A minimal JSON vertex can be created with a tenant slug, key, type, access mode, and initial value.
curl -X POST https://n-v.io/api/v1/vertices \
-H "Content-Type: application/json" \
-d '{
"tenantSlug": "acme",
"vertexKey": "build-status",
"type": 2,
"accessMode": 1,
"value": "{\"status\":\"pending\"}"
}'
Read and write
Once created, the vertex is available through an intuitive tenant/key URL. GET reads. POST writes, appends, or signals depending on the vertex type. PUT replaces.
Write status
POST /acme/build-status
{ "status": "passed" }
Read status
GET /acme/build-status
{ "status": "passed" }
Signal events
A signal vertex is a URL that receives commands or events. It is ideal for automation triggers, device commands, agent coordination, and simple machine-to-machine notifications.
curl -X POST https://n-v.io/factory/reboot-device-17 \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"command":"reboot","issuedBy":"agent-01"}'
Authentication overview
| Mode | Use it for | Example |
|---|---|---|
| Public | Open values, public signals, demo endpoints | GET /demo/status |
| Bearer token | Server-to-server writes and reads | Authorization: Bearer {token} |
| Basic auth | Simple legacy integrations | Authorization: Basic ... |
| Tenant user | Admin and team-owned resources | Authenticated session |
| Signed access token | Expiring read/write links | ?token={signedToken} |
| OIDC / SAML | Enterprise federation | Designed for future policy providers |
TTL usage
TTL makes vertices useful for ephemeral communication. Use expiration for temporary handoffs, one-time outputs, short-lived access links, incident channels, or command messages that should not remain valid forever.
POST /api/v1/vertices
{
"tenantSlug": "ops",
"vertexKey": "incident-bridge",
"type": 2,
"accessMode": 5,
"expiresUtc": "2026-05-01T01:00:00Z"
}
Example workflows
Pipeline posts build status. Release tooling reads it before deployment.
POST /acme/build-status GET /acme/build-status
An AI worker writes its final output to a write-once operation result vertex.
POST /agents/output-42 GET /agents/output-42
A control service posts a command. A device polls and acknowledges through another vertex.
POST /factory/reboot-device-17 GET /factory/reboot-device-17
When should I use Node Vertex?
Use Node Vertex when the communication is simple but important: a status, a result, a signal, a mailbox, a file, a temporary payload, or a coordination point. Build a full API when you need a complex domain model, many custom operations, or transactional business logic. Use a vertex when you need a secure endpoint now.