API Reference

Benchmarked against: Anthropic — API Reference Protocol: MCP (Model Context Protocol) Scope: Complete reference for SuperPortia's tool-based API surface

SuperPortia's API is exposed through MCP servers. Unlike traditional REST APIs, these tools are designed to be discovered and invoked by AI agents through natural language reasoning.

---

API surface overview

Domain	Server	Tool count	Description
Knowledge	Cloud UB	12	Search, ingest, CRUD, stats
Work Orders	Cloud UB	10	Create, status, review, dispatch
Communication	Cloud UB	5	Messaging, mailbox, heartbeat
Operations	Cloud UB	3	Factory floor, captain location, SRE
Intelligence	Local UBI	4	Intel search, patrol, web search, call_model
File Operations	Local UBI	5	Read, write, edit, list, search
Infrastructure	Cloudflare	2	Execute, search OpenAPI spec
Database	Supabase	15+	SQL, migrations, edge functions
Browser	Chrome	12+	Navigation, screenshots, interaction

---

Knowledge API

search_brain

Search the Universal Brain using hybrid search (FTS5 keyword + semantic vector).

Parameter	Type	Required	Default	Description
query	string	Yes	—	Search query (English recommended)
limit	number	No	10	Maximum results

ingest_fragment

Ingest content into UB through the MTAAA 5-node pipeline.

Parameter	Type	Required	Default	Description
path	string	Yes	—	File path, text content, or URL
input_type	string	No	file	file, text, url, screenshot
source	string	No	manual	manual, nq_alpha, ss_vault, downloads, api

get_entry

Retrieve a single UB entry by ID.

Parameter	Type	Required	Description
entry_id	string	Yes	Entry ID (e.g., ub-a1b2c3d4e5f6)

get_recent

Get the most recently ingested entries.

Parameter	Type	Required	Default	Description
limit	number	No	10	Number of entries

search_by_category

Browse entries by category.

Parameter	Type	Required	Default	Description
category	string	Yes	—	Category name
subcategory	string	No	—	Subcategory filter
limit	number	No	20	Maximum results

update_entry

Update fields on an existing entry.

Parameter	Type	Required	Description
entry_id	string	Yes	Entry to update
title	string	No	New title
content	string	No	New content
tags	string	No	New tags (comma-separated)

get_stats

Get UB ingestion statistics.

No parameters.

---

Work Order API

create_work_order

Create a new work order.

Parameter	Type	Required	Description
title	string	Yes	Must start with [Project-Category] prefix
assignee	string	Yes	Valid agent identity
project	string	Yes	Project name (e.g., SS1, SP)
description	string	No	Detailed work description
priority	string	No	high, medium (default), low
due_date	string	No	YYYY-MM-DD format
estimated_hours	number	No	Estimated hours
acceptance_criteria	string	No	What defines completion

list_work_orders

Query work orders with filters.

Parameter	Type	Required	Default	Description
status	string	No	—	Filter by status
project	string	No	—	Filter by project
assignee	string	No	—	Filter by assignee
include_completed	boolean	No	false	Include completed/cancelled
limit	number	No	20	Maximum results

accept_work_order

Accept a pending work order.

Parameter	Type	Required	Default	Description
order_id	string	Yes	—	WO ID
assignee	string	No	Auto	Agent identity

update_work_order_status

Change work order status (must follow state machine).

Parameter	Type	Required	Description
order_id	string	Yes	WO ID
new_status	string	Yes	Target status
notes	string	Conditional	Required for blocked/unblock

complete_work_order

Submit work order for review.

Parameter	Type	Required	Description
order_id	string	Yes	WO ID
summary	string	Yes	Completion summary
actual_hours	number	Recommended	Hours spent

verify_work_order

Approve or reject a work order (Captain only).

Parameter	Type	Required	Description
order_id	string	Yes	WO ID
approved	boolean	Yes	true = approve, false = reject
notes	string	No	Review comments

dispatch_work_order

Dispatch a work order to an engine for execution.

Parameter	Type	Required	Default	Description
work_order_id	string	Yes	—	WO ID
engine	string	No	claude	Engine: groq, gemini, claude, ingest, etc.

---

Communication API

agent_heartbeat

Register agent as online.

No required parameters.

check_agent_mailbox

Check agent's mailbox.

Parameter	Type	Required	Default	Description
agent_name	string	No	Auto	Agent identity
unread_only	boolean	No	false	Only unread messages

send_agent_message

Send a message to another agent.

Parameter	Type	Required	Description
to	string	Yes	Recipient agent identity
subject	string	Yes	Message subject
body	string	Yes	Message body (markdown)
priority	string	No	normal or urgent

factory_floor_status

Get real-time overview of team status and active work.

No parameters.

---

Intelligence API

intel_search

Search any topic and auto-ingest findings into UB.

Parameter	Type	Required	Default	Description
query	string	Yes	—	Search query (English)
engine	string	No	groq	groq (free) or gemini (citations)
tags	string	No	—	Tags for ingested intel

search_web

Delegate web search to low-cost engines.

Parameter	Type	Required	Default	Description
query	string	Yes	—	Search query
engine	string	No	groq	groq or gemini

call_model

Call a low-cost LLM for subtasks.

Parameter	Type	Required	Default	Description
prompt	string	Yes	—	Prompt text
provider	string	No	groq	groq, gemini, deepseek, mistral, zhipu
temperature	number	No	0.3	Creativity 0.0-1.0

---

Authentication

All API calls are authenticated via environment variables:

Variable	Purpose
SP_CLOUD_UB_URL	Cloud UB endpoint
SP_API_KEY	API authentication key
SP_SHIP_ID	Ship identity (SS1, SS2, SS3)
SP_AGENT_ID	Agent identity

---

Related pages

Page	Relationship
MCP Tool Discovery	How agents find tools
Agentic API	Industry concept alignment
Setup MCP	Configuration guide