API Reference

A complete, plain-English guide to endpoints, auth, and data flows.

Who This Is For

Developers integrating Decillion AI into apps, teams building shared workspaces, and anyone who needs agents, storage, and realtime signals in one system.

Start Here

Overview CLI Reference

Quick Start

1. Login

Call /users/login with your username and email token to receive your private key.

2. Authenticate

Use authenticate after connecting to validate your session.

3. Read or Write

Use /points/read to load your spaces and /points/signal for messages.

4. Manage Apps

Create apps and machines with /apps/create and /machines/create.

Auth & Security

Every request is signed with your private key.
Login returns a private key used for RSA-PSS signatures.
Use the SDK to manage signatures and connection details.

Transport

WebSocket TLS: wss://api.decillionai.com:8076
TCP TLS: api.decillionai.com:8077
HTTP Storage: https://api.decillionai.com:3000

Response Format

Responses include a resCode and an obj. Use resCode === 0 to check for success.

Authentication & Users

/users/login

Create or log into a user and receive a private key for signing requests.

Parameters

username: string
emailToken: string
metadata.public.profile.name: string

Called with empty userId. Returns user and privateKey on success.

authenticate

Validate the current session for the logged-in user.

Parameters

(none)

Uses your userId and signature in the request envelope.

/users/get

Fetch a user profile by id.

Parameters

userId: string

/users/find

Find a user by username.

Parameters

username: string

/users/update

Update your user metadata (public or private).

Parameters

metadata: object

/users/meta

Read a metadata path for a user.

Parameters

userId: string
path: string

Example path: private.contacts or private.settings.privacy

/users/list

List users with pagination and search.

Parameters

offset: number
count: number
param: string
query: string

/users/lockToken

Lock tokens for payments or gated actions.

Parameters

amount: number
type: string
target: string

Returns tokenId on success.

logout

Invalidate the local session and clear cached data.

Parameters

(none)

/users/delete

Delete your account and log out.

Parameters

(none)

Points (Spaces, Chats, Groups)

/points/create

Create a point (home, 1-to-1, group, etc).

Parameters

tag: string
members: map<string, bool>
isPublic: boolean
persHist: boolean
orig: string
parentId: string | null
metadata.public.profile.title: string
metadata.public.profile.avatar: string

/points/update

Update a point’s visibility, history, or metadata.

Parameters

pointId: string
isPublic: boolean
persHist: boolean
metadata: object

/points/meta

Read a metadata path for a point.

Parameters

pointId: string
path: string

/points/delete

Delete a point by id.

Parameters

pointId: string

/points/get

Get a single point and its metadata.

Parameters

pointId: string
includeMeta: boolean

/points/read

Read your points (pagination, tag, origin).

Parameters

offset: number
count: number
tag: string
orig: string

/points/list

List public points by query.

Parameters

offset: number
count: number
query: string

/points/join

Join a public point.

Parameters

pointId: string

/points/leave

Leave a point.

Parameters

pointId: string

/points/history

Load message history for a point.

Parameters

pointId: string
beforeId: string
ids: string[]
count: number

/points/signal

Send a signal or message to a point.

Parameters

pointId: string
userId: string
type: string
data: string
temp: boolean

Used for chat messages and system events.

/points/addMember

Add a member to a point.

Parameters

pointId: string
userId: string
metadata: object

/points/updateMember

Update a member’s metadata in a point.

Parameters

pointId: string
userId: string
metadata: object

/points/removeMember

Remove a member from a point.

Parameters

pointId: string
userId: string

/points/readMembers

List members in a point.

Parameters

pointId: string

/points/getDefaultAccess

Get the default access policy for points.

Parameters

(none)

/points/updateMemberAccess

Update a member’s access permissions.

Parameters

pointId: string
userId: string
access: object

/points/updateMachineAccess

Update a machine’s access permissions in a point.

Parameters

pointId: string
machineId: string
access: object

/points/listApps

List apps attached to a point.

Parameters

pointId: string

/points/addApp

Attach an app to a point.

Parameters

pointId: string
appId: string
machinesMeta: object[]

/points/removeApp

Detach an app from a point.

Parameters

pointId: string
appId: string

/points/addMachine

Attach a machine to an app in a point.

Parameters

pointId: string
appId: string
machineMeta: object

/points/updateMachine

Update a machine attached to an app in a point.

Parameters

pointId: string
appId: string
machineMeta: object

/points/removeMachine

Remove a machine from an app in a point.

Parameters

pointId: string
appId: string
machineId: string
identifier: string

Invites

/invites/create

Invite a user to a point.

Parameters

pointId: string
userId: string

/invites/cancel

Cancel an invite.

Parameters

pointId: string
userId: string

/invites/accept

Accept an invite to a point.

Parameters

pointId: string

/invites/decline

Decline an invite.

Parameters

pointId: string

/invites/listUserInvites

List invites for the current user.

Parameters

(none)

/invites/listPointInvites

List users invited to a point.

Parameters

pointId: string

Chains

/chains/create

Create a chain with participants.

Parameters

participants: map<string, number>
isTemp: boolean

/chains/submitBaseTrx

Submit a base transaction to a chain.

Parameters

chainId: number
key: string
payload: object
signature: string

Apps & Machines

/apps/create

Create a new app.

Parameters

chainId: string
username: string
metadata: object

/apps/updateApp

Update an app’s metadata.

Parameters

appId: string
metadata: object

/apps/deleteApp

Delete an app by id.

Parameters

appId: string

/apps/list

List apps (pagination).

Parameters

offset: number
count: number

/apps/myCreatedApps

List apps created by the current user.

Parameters

(none)

/machines/create

Create a machine for an app.

Parameters

username: string
appId: string
path: string
runtime: string
comment: string
publicKey: string

/machines/deploy

Deploy bytecode to a machine.

Parameters

machineId: string
byteCode: string
runtime: string
metadata: object

/apps/updateMachine

Update a machine’s path.

Parameters

machineId: string
path: string

/apps/deleteMachine

Delete a machine.

Parameters

machineId: string

/machines/list

List machines (pagination).

Parameters

offset: number
count: number

/machines/listAppMachines

List machines for a specific app.

Parameters

appId: string

Storage

/storage/upload

Upload a file to a point (base64 data).

Parameters

pointId: string
data: base64 string
fileId: string | null

/storage/download

Download a file by fileId.

Parameters

pointId: string
fileId: string

/storage/deleteUserEntity

Delete a user entity (e.g. avatar).

Parameters

entityId: string

/storage/deletePointEntity

Delete a point entity (e.g. avatar or background).

Parameters

entityId: string
pointId: string

PC Runtime

/pc/runPc

Start a personal compute runtime.

Parameters

(none)

/pc/execCommand

Execute a command on a VM.

Parameters

vmId: string
command: string

Common Patterns

Messaging

Use /points/signal to send messages and events inside a point.

Members

Invite, accept, and manage access with the/invites endpoints.

Apps + Machines

Create an app, then add machines to deploy runtimes and workflows.

Storage

Use entity uploads for avatars and assets. Use file upload/download for point-level files.

Events & Realtime

The SDK emits realtime updates using event keys. Listen to these for new points and messages.

points/create — when a point is created or joined.

points/signal — incoming messages or signals for a point.

pc/message — stream output from PC runtime.

Storage HTTP Details

Entity uploads and downloads use HTTPS and signed headers. The SDK handles signing, but these are the raw formats:

Upload user entity: POST/storage/uploadUserEntity

Headers: User-Id, Input (JSON), Signature

Body: raw bytes

Download user entity: POST/storage/downloadUserEntity

Headers: User-Id, Input-Length

Body: Input JSON bytes + Signature bytes

Need Help?

If you need access tokens or SDK help, contact support.

Contact Support CLI Docs

API Reference

Who This Is For

Start Here

Quick Start

On This Page

Auth & Security

Transport

Response Format

Authentication & Users

Points (Spaces, Chats, Groups)

Invites

Chains

Apps & Machines

Storage

PC Runtime

Common Patterns

Events & Realtime

Storage HTTP Details

Need Help?