User API Reference

The User API (Client API) runs on port 8443. All endpoints use X-Session-Token: amb_st_... authentication except POST /v1/clients/register.

Authentication

The Ambassador Client handles authentication automatically. These endpoints are documented for direct API access or building custom clients.

# Register (uses preshared key, no session token needed)
curl -k -X POST https://localhost:8443/v1/clients/register \
  -H "Content-Type: application/json" \
  -d '{
    "friendly_name": "My Client",
    "host_tool": "claude_desktop",
    "preshared_key": "amb_pk_your_key"
  }'
# → {"session_token": "amb_st_...", "user_id": "uuid", "ca_fingerprint": "sha256:..."}

# Use session token for all subsequent calls
curl -k https://localhost:8443/v1/tools \
  -H "X-Session-Token: amb_st_your_token"

Clients

POST /v1/clients/register

Register a new Ambassador Client. Uses the preshared key. Returns a session token.

Request:

{
  "friendly_name": "VS Code - Work Laptop",
  "host_tool": "vscode",
  "preshared_key": "amb_pk_your_preshared_key"
}

host_tool values: claude_desktop, vscode, claude_code, cursor, other

Response:

{
  "session_token": "amb_st_XXXX",
  "user_id": "uuid",
  "client_id": "uuid",
  "ca_fingerprint": "sha256:XXXX",
  "session_ttl_seconds": 86400
}

GET /v1/clients

List the current user's registered clients.

Response:

[
  {
    "id": "uuid",
    "friendly_name": "VS Code - Work Laptop",
    "host_tool": "vscode",
    "active": true,
    "registered_at": "2026-02-19T10:00:00Z",
    "last_seen": "2026-02-19T14:30:00Z"
  }
]

DELETE /v1/clients/:id

Deactivate a client. Invalidates its session token immediately.

Session

POST /v1/session/heartbeat

Keep the session alive. The Ambassador Client calls this periodically.

Response:

{
  "ok": true,
  "ttl_seconds": 86400,
  "catalog_version": "v_hash"
}

If catalog_version has changed, the client should re-fetch the tool catalog.

Tools

GET /v1/tools

Get the personalized tool catalog for the current client — all tools from active subscriptions, filtered to tools enabled on this client.

Response:

{
  "tools": [
    {
      "name": "github.search_code",
      "description": "Search code across GitHub repositories",
      "input_schema": {
        "type": "object",
        "properties": {
          "query": {"type": "string", "description": "Search query"}
        },
        "required": ["query"]
      }
    }
  ],
  "catalog_version": "v_hash"
}

POST /v1/tools/call

Invoke a tool.

Request:

{
  "tool": "github.search_code",
  "arguments": {
    "query": "authentication middleware"
  }
}

Response (success):

{
  "content": [
    {
      "type": "text",
      "text": "Found 42 results..."
    }
  ],
  "is_error": false
}

Response (tool error):

{
  "content": [
    {
      "type": "text",
      "text": "GitHub API error: rate limit exceeded"
    }
  ],
  "is_error": true
}

Response (blocked):

{
  "error": "Forbidden",
  "details": "Tool github.create_pr is currently disabled"
}

Marketplace

GET /v1/marketplace

Browse available MCPs. Returns MCPs published by admin and assigned to the user's groups.

Response:

[
  {
    "id": "mcp_uuid",
    "name": "github",
    "display_name": "GitHub",
    "description": "GitHub API — search code, manage PRs, issues",
    "tags": ["code", "version-control"],
    "tool_count": 8,
    "subscribed": false,
    "requires_credentials": true
  }
]

Subscriptions

POST /v1/subscriptions

Subscribe to an MCP.

Request:

{
  "mcp_id": "mcp_uuid",
  "credentials": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
  },
  "enabled_tools": ["github.search_code", "github.list_issues"]
}

Omit enabled_tools to enable all tools.

GET /v1/subscriptions

List active subscriptions.

GET /v1/subscriptions/:id

Get subscription details including enabled tools and credential status.

PUT /v1/subscriptions/:id

Update an existing subscription — change credentials or tool selection.

{
  "credentials": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_new_token"
  },
  "enabled_tools": ["github.search_code"]
}

DELETE /v1/subscriptions/:id

Unsubscribe. Deletes stored credentials for this MCP.

Health

GET /health

No authentication required.

{"status": "ok", "version": "0.8.0-beta.1"}

Error responses