Semesh API Docs

One API key for models, tools, apps, agents, and user services.

Use the CLI when a human or agent is operating in a terminal. Use HTTP when embedding Semesh in a server. Both use the same Semesh account, Aev, service catalog, and execution contracts.

Base URL

HTTP endpoint

https://semesh.io

Auth

Bearer key

Authorization: Bearer $SEMESH_API_KEY

CLI

Install package

npm install semesh@latest --prefer-online

Agents

Read first

/agent.md

CLI quickstart

npm install semesh@latest --prefer-online
	./node_modules/.bin/semesh doctor --require-latest
	./node_modules/.bin/semesh login
	./node_modules/.bin/semesh search "web research" --json
	./node_modules/.bin/semesh show web.search --json
	./node_modules/.bin/semesh call web.search --input '{"q":"Semesh docs"}' --json

HTTP quickstart

curl "https://semesh.io/v1/services/search?q=web+research" \
  -H "Authorization: Bearer $SEMESH_API_KEY"

curl "https://semesh.io/v1/tools/web.search" \
  -H "Authorization: Bearer $SEMESH_API_KEY"

Service Search

Search before invoking.

GET /v1/services/search?q=... returns service cards and matched operations.

GET /v1/services/{id} returns the card, category, descriptions, entrypoints, and operation refs.

Tool Protocol

Inspect exact schemas.

GET /v1/tools lists executable tools. GET /v1/tools/{id} shows input schema, pricing metadata, and wait behavior.

Canonical invoke is POST /v1/capabilities/{id}/invoke. POST /v1/tools/{id}/call is a compatibility alias only. Prefer the CLI wrapper for humans and agents. A direct authenticated request authorizes ordinary paid invoke; deploy and payment actions remain governed by live server/preflight availability.

OpenAI-compatible

Use existing SDKs.

Text model routes support OpenAI-style clients with baseURL=https://semesh.io/v1 and your Semesh key.

curl https://semesh.io/v1/chat/completions \
  -H "Authorization: Bearer $SEMESH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"mistralai/mistral-medium-3-5","messages":[{"role":"user","content":"Hello"}]}'

Apps, Agents, Workers

Publish services other users can call.

Inspect app deployment with semesh deploy preflight, publish App APIs/commands, upload hosted agents, or share local worker offers. A deploy continues only when admission allows it. Mechanically valid publication is automatic, self-service, and discoverable once readiness checks pass, without a default manual approval queue.