API Overview

Noorle exposes three request surfaces. They are separate hosts with separate protocols, separate error formats, and separate authentication rules. Pick the one that matches what you are doing.

Surface	Host	Protocol	Use it for
Management API	`api.noorle.com`	REST over HTTPS	Uploading plugins, listing capabilities, resolving approval gates, starting workflow runs
MCP gateway	`mcp-{handle}.noorle.com`	MCP over Streamable HTTP	Giving an MCP client access to the tools you bound to that gateway
Agent gateway	`agent-{handle}.noorle.com`	A2A over JSON-RPC 2.0	Sending messages to one of your agents from another system

Each gateway host is derived from the gateway’s or agent’s handle, not its UUID. Every account gets its own gateway hosts; there is no shared platform-wide MCP server.

These are the production hosts. Staging uses noorle.app and development uses noorle.dev with the same prefixes.

Management API

Path-versioned under /v1. Responses wrap their payload in a data envelope:

{ "data": [ /* ... */ ] }

curl https://api.noorle.com/v1/capabilities \
  -H "Authorization: Bearer eyJhbGc..."

The two OAuth routes are the exception — /oauth/device/authorize and /oauth/token return their fields bare, with no data wrapper.

What it covers

The management API is a narrow CLI and integration surface, not a mirror of the Portal. It exists so a script, a CI job, or the CLI can do the handful of things that need to happen without a browser. Read this list before you design against it.

Area	What the API can do
Capabilities	List them; upload a plugin archive
Plugin builds	Create, list, read, cancel
Skills	Full lifecycle — create, read, update, delete, plus content, bindings, import, and generate
Workflow runs	Start a run; read status; cancel; approve; signal
Approval gates	List what is pending for a thread, a workflow run, or the account; submit a decision
Autonomy	Read and set per-agent, per-user, and account-wide policy; read decision history
Agents	Attach and detach workflows; browse and read the agent’s home directory; read its quota
Gateways	Attach and detach workflows
Attachments	Read account quota; regenerate a presigned URL

Most Portal areas have no API equivalent at all. There is no create, update, or delete for agents, gateways, connectors, knowledge bases, users, API keys, threads, or workflows — and no endpoints for billing, activity, notifications, chat, or profile.Note the shape of the two rows above that mention agents and gateways: those endpoints manage a workflow association and an agent’s files. They do not create, configure, or delete the agent or gateway itself.

Everything outside that table happens in the Portal. If you are planning an integration, treat the table as the customer-facing surface rather than assuming a REST route exists for each screen you can see — it omits a few narrow, non-CRUD routes that exist for specific integrations rather than general use: GET /v1/noorle-cli/config (CLI bootstrap), POST /v1/identity/verify (link a platform identity), GET /v1/files/{id} (a presigned redirect), and GET /v1/agents/{agent_id}/skills.

REST reference

Capabilities, plugin upload, and the OAuth device flow.

MCP gateway

The transport is Streamable HTTP, mounted at the gateway origin. There is no separate /sse endpoint and no WebSocket transport — JSON-RPC responses come back as text/event-stream frames on the POST response.

curl -X POST https://mcp-my-gateway.noorle.com/ \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

The gateway advertises tools only. It does not implement MCP resources, prompts, logging, or completions.

MCP reference

Transport, session posture, tools/list, tools/call, and what is not implemented.

Agent gateway

A2A 1.0 over JSON-RPC 2.0. Every method is a POST to the origin root — the method name is in the JSON-RPC envelope, not the path. Method names are PascalCase (SendMessage, GetTask), not the slash-separated 0.x names.

curl -X POST https://agent-my-agent.noorle.com/ \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "SendMessage",
    "params": {
      "message": {
        "messageId": "6f1b...",
        "role": "ROLE_USER",
        "parts": [{"text": "What is the status of order 4471?"}]
      }
    }
  }'

The agent card at GET /.well-known/agent-card.json is public and tells callers what authentication to attach.

A2A reference

The eleven methods, task lifecycle, streaming, and the agent card.

Authentication at a glance

Surface	Accepted credentials
Management API	API key (`ak-…`) or a device-flow JWT, on `Authorization`
MCP gateway	API key or a JWT minted by that gateway’s own OAuth server. Public gateways accept unauthenticated calls
Agent gateway	API key belonging to a service principal, or a JWT scoped to that agent

There is no session cookie on any of these surfaces, and no query-parameter token form.

Authentication

Header forms, the device flow, and per-gateway OAuth.

Errors

The three surfaces do not share an error format. The management API returns a flat JSON body whose category field determines the HTTP status; the gateways return JSON-RPC errors in the response envelope.

Errors and limits

Status mapping, JSON-RPC codes, and the limits that actually exist.

Overview

REST API

MCP Protocol

A2A Protocol

Noorle CLI

Management API

What it covers

REST reference

MCP gateway

MCP reference

Agent gateway

A2A reference

Authentication at a glance

Authentication

Errors

Errors and limits

Choosing a surface

Next steps

​Management API

​What it covers

REST reference

​MCP gateway

MCP reference

​Agent gateway

A2A reference

​Authentication at a glance

Authentication

​Errors

Errors and limits

​Choosing a surface

​Next steps

Management API

What it covers

MCP gateway

Agent gateway

Authentication at a glance

Errors

Choosing a surface

Next steps