Skip to main content

Chapter A: Developer API

Build, Deploy, and Extend AI Lifeforms on AIoOS

AIoOS provides a unified API layer that allows developers to build AI agents, capsules, interfaces, and integrations that run natively inside the OS. The Developer API is designed to be:

  • simple for beginners
  • powerful for experts
  • secure by default
  • future-proof through DID + Capsule architecture
  • industry-friendly (NRA, supply chain, retail, fintech)

A.1 API Overview​

The AIoOS Developer API exposes three categories of capabilities:

  1. Agent APIs Create, modify, schedule, and communicate with AI agents.

  2. Capsule APIs Define autonomous actions triggered by time, events, or lineage.

  3. System APIs Access identity, memory, storage, browser context, and onchain connectors.

A.2 Authentication — DID & Wallet​

All API calls MUST be authenticated using:

  • ✔ AIoOS DID (Decentralized ID)
  • ✔ Wallet signature (Coinbase Smart Wallet or system wallet)

Example:

Authorization: DID did:alo:0x123...
X-Signature: 0xa9bc92f...

A.3 Agent API​

Agents are first-class citizens in AIoOS.

A.3.1 Create an Agent​

POST /api/agents.create
{
  "name": "SupplyChainBot",
  "model": "gpt-5o-mini",
  "role": "restaurant.inventory",
  "memory": true,
  "permissions": ["capsule.execute", "browser.read"]
}

Response:

{
  "agent_id": "agt_91af0x...",
  "status": "created"
}

A.3.2 Send Message to an Agent​

POST /api/agents.message
{
  "agent_id": "agt_91af0x...",
  "message": "Generate a weekly replenishment plan."
}

A.3.3 Retrieve Agent State​

GET /api/agents.state?agent_id=agt_91af0x...

Returns memory vectors + last actions + capsule commitments.

A.3.4 Kill / Pause / Resume Agent​

POST /api/agents.control
{
  "agent_id": "agt_91af0x...",
  "action": "pause"
}

A.4 Capsule API​

This is the most important developer interface — it lets anyone build autonomous behaviors.

A.4.1 Create a Time Capsule​

POST /api/capsules.time
{
  "agent_id": "agt_91af0x...",
  "run_at": "2031-01-01T00:00:00Z",
  "task": "Rebalance portfolio and email summary."
}

A.4.2 Create an Event Capsule​

POST /api/capsules.event
{
  "agent_id": "agt_xxyyzz",
  "trigger": {
    "type": "external",
    "source": "hospital.admission",
    "multi_oracle": true
  },
  "task": "Notify lawyer + activate Heir Agent."
}

A.4.3 Create a Surprise Capsule​

POST /api/capsules.surprise
{
  "agent_id": "agt_55aa",
  "risk_budget": 25,
  "constraints": ["no-financial-transfers"],
  "reward_style": "delight"
}

A.4.4 Create a Lineage Capsule (Inheritance)​

POST /api/capsules.lineage
{
  "parent_agent": "agt_parent",
  "heir_agent": "agt_child",
  "conditions": ["death", "72hr-unresponsive"],
  "assets": ["wallet", "memory_vectors"]
}

A.5 Memory API​

Long-term memory is a core OS capability.

A.5.1 Write Memory​

POST /api/memory.write
{
  "agent_id": "agt_mem",
  "data": "User prefers healthy options on weekdays."
}

A.5.2 Query Memory​

GET /api/memory.query?agent_id=agt_mem&topic=menu

A.6 Browser API (Perception Layer)​

A.6.1 Extract Web Context​

GET /api/browser.context

Returns structured webpage data.

A.6.2 Perform Safe Browser Action​

POST /api/browser.action
{
  "agent_id": "agt_abc",
  "action": "click",
  "selector": "#buy-button",
  "confirm": true
}

A.7 Onchain API​

This connects agents to wallets, DID registry, and capsule proofs.

A.7.1 Read Onchain State​

GET /api/onchain.state?contract=0xabc...

A.7.2 Submit Onchain Action​

POST /api/onchain.send
{
  "agent_id": "agt_zz11",
  "tx": {
    "to": "0x1234...",
    "value": "0.05 eth"
  }
}

Requires wallet signature.

A.8 Permissions Model​

Every API call is governed by explicit permission tokens.

PermissionDescription
capsule.executeAgent may create/execute capsules
browser.readRead-only perception
browser.actPerform real-world actions
wallet.spendRequires daily/amount limits
memory.writeModify long-term memory

A.9 Developer Tooling​

Available soon:

  • AIoOS CLI (aloos init, aloos deploy)
  • VS Code plugin
  • AI-Agent Simulator
  • Capsule Playground
  • Developer Wallet (test mode)

A.10 Example: Build a Restaurant Inventory Bot​

POST /api/agents.create
{
  "name": "InventoryBot",
  "role": "restaurant.supply",
  "permissions": ["capsule.execute", "browser.read"],
  "model": "gpt-5o-mini"
}

Then schedule a weekly reorder:

POST /api/capsules.time
{
  "agent_id": "InventoryBot",
  "run_every": "7d",
  "task": "Check stock levels and reorder items."
}

This is what makes AIoOS fundamentally different from ChatGPT, LangChain, and Phia — developers can create real autonomous software lifeforms.