API Overview

Noorle Platform provides three APIs for different use cases: REST for administration, MCP for agent tools, and A2A for agent-to-agent communication.

API Endpoints

Base URLs

Service	Host	Purpose
REST API	`api.noorle.com`	Administrative operations (plugins, agents, configurations)
MCP Gateway	`mcp-{id}.noorle.com`	Model Context Protocol for LLM tool access
Agent Gateway	`agent-{id}.noorle.com`	Agent-to-Agent communication protocol

Versioning

Current API version: v1 REST API uses path versioning: /v1/capabilities, /v1/agents, etc.

Three API Types

1. REST API (`api.noorle.com`)

Traditional HTTP REST API for administration. Use for:

Plugin management (upload, list, versions)
Agent configuration
OAuth device flow authentication
Capability management

Example:

curl -X POST https://api.noorle.com/v1/capabilities/upload \
  -H "X-API-Key: YOUR_KEY" \
  -F "plugin=@my-plugin.npack"

REST API Reference →

2. MCP Gateway (`mcp-{id}.noorle.com`)

Model Context Protocol server providing tools to LLMs and agents. Use for:

Discovering available tools
Calling tools (capabilities)
Accessing resources
Retrieving prompts

Transports:

Streamable HTTP - SSE for events, POST for requests
HTTP - Stateless request-response

Example:

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "my_plugin_greet",
        "description": "Greet a person"
      }
    ]
  }
}

MCP Reference →

3. A2A Gateway (`agent-{id}.noorle.com`)

Agent-to-Agent protocol for multi-agent workflows. Use for:

Sending messages to agents
Streaming responses
Querying agent capabilities
Managing tasks

Transports:

JSON-RPC 2.0 - Over HTTP/WebSocket
SSE (Server-Sent Events) - For streaming

Example:

// Send message
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": "What's the weather?",
    "context": {}
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "text": "The weather is sunny...",
    "task_id": "task-123"
  }
}

A2A Reference →

Authentication

All APIs support multiple authentication methods:

API Key (Header)

curl -H "X-API-Key: ak-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4s9t0u1v2w3x4y5z6" \
  https://api.noorle.com/v1/capabilities

Bearer Token (OAuth)

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

Device Flow (CLI)

noorle login
# Prompts with verification URL and code
# Exchanges device code for OAuth token

Authentication Guide →

Request Format

All APIs use JSON for request and response bodies.

Headers

Content-Type: application/json
Authorization: Bearer {jwt_token} (for JWT auth) or X-API-Key: {api_key} (for API key auth)
User-Agent: {client-name}/{version}
X-Request-ID: {trace-id}  (optional)

Common Request Fields

{
  "jsonrpc": "2.0",        // MCP/A2A only
  "id": 1,                 // Request ID for correlation
  "method": "tools/list",  // MCP/A2A method
  "params": {},            // Method parameters
  "body": {}               // REST API body
}

Response Format

Success Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [...],
    "resources": [...]
  }
}

HTTP Status: 200 OK

Error Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": {
      "details": "Something went wrong"
    }
  }
}

HTTP Status: 4xx (client error) or 5xx (server error)

Rate Limiting

All APIs implement rate limiting:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1711123200

When limit reached, response is:

{
  "error": {
    "code": 429,
    "message": "Too many requests"
  }
}

Wait until X-RateLimit-Reset timestamp before retrying. Rate Limits →

Error Codes

Common HTTP Status Codes

Code	Meaning	Action
200	OK	Success
201	Created	Resource created
400	Bad Request	Fix your request
401	Unauthorized	Check authentication
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn’t exist
429	Too Many Requests	Wait before retrying
500	Internal Error	Server error, retry later

Error Reference →

JSON-RPC Error Codes

MCP and A2A use JSON-RPC 2.0 error codes:

{
  "code": -32700,
  "message": "Parse error"
}

Code	Message	Meaning
-32700	Parse error	Invalid JSON
-32600	Invalid Request	Bad method/params
-32601	Method not found	Method doesn’t exist
-32602	Invalid params	Wrong parameters
-32603	Internal error	Server error

Testing APIs

Using cURL

# List capabilities
curl -X GET https://api.noorle.com/v1/capabilities \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json"

Using Postman

Import OpenAPI spec from https://api.noorle.com/openapi.json
Set X-API-Key header in collection
Execute requests

Using SDK

Official SDKs available:

JavaScript/TypeScript - npm install @noorle/sdk
Python - pip install noorle-sdk
Go - go get github.com/noorle/sdk-go

import { NoorleClient } from "@noorle/sdk";

const client = new NoorleClient({
  apiKey: "YOUR_API_KEY"
});

// List capabilities
const caps = await client.capabilities.list();

Choosing an API

API Clients

Official Clients:

Noorle CLI - Command-line tool for administration
Console - Web UI for all operations
SDKs - Typed clients for your language

Third-party tools:

Postman Collection - Import and test APIs
OpenAPI Schema - Integrate with code generators
Webhooks - Event-driven integrations (future)

Common Workflows

Upload a Plugin

Build locally: noorle plugin build
POST to /v1/capabilities/upload
Get capability_id and active_version
Plugin available immediately

Call a Tool

Connect to MCP gateway
Call tools/list to discover tools
Call tools/call with tool name and parameters
Get result

Send Message to Agent

Connect to A2A gateway
GET /.well-known/agent-card.json for capabilities
POST /message/send with message and context
Get response and task_id
Poll /tasks/{id} for status

Overview

REST API

MCP Protocol

A2A Protocol

Noorle CLI

API Endpoints

Base URLs

Versioning

Three API Types

1. REST API (`api.noorle.com`)

2. MCP Gateway (`mcp-{id}.noorle.com`)

3. A2A Gateway (`agent-{id}.noorle.com`)

Authentication

API Key (Header)

Bearer Token (OAuth)

Device Flow (CLI)

Request Format

Headers

Common Request Fields

Response Format

Success Response

Error Response

Rate Limiting

Error Codes

Common HTTP Status Codes

JSON-RPC Error Codes

Testing APIs

Using cURL

Using Postman

Using SDK

Choosing an API

API Clients

Common Workflows

Upload a Plugin

Call a Tool

Send Message to Agent

Next Steps

​API Endpoints

​Base URLs

​Versioning

​Three API Types

​1. REST API (api.noorle.com)

​2. MCP Gateway (mcp-{id}.noorle.com)

​3. A2A Gateway (agent-{id}.noorle.com)

​Authentication

​API Key (Header)

​Bearer Token (OAuth)

​Device Flow (CLI)

​Request Format

​Headers

​Common Request Fields

​Response Format

​Success Response

​Error Response

​Rate Limiting

​Error Codes

​Common HTTP Status Codes

​JSON-RPC Error Codes

​Testing APIs

​Using cURL

​Using Postman

​Using SDK

​Choosing an API

​API Clients

​Common Workflows

​Upload a Plugin

​Call a Tool

​Send Message to Agent

​Next Steps

API Endpoints

Base URLs

Versioning

Three API Types

1. REST API (`api.noorle.com`)

2. MCP Gateway (`mcp-{id}.noorle.com`)

3. A2A Gateway (`agent-{id}.noorle.com`)

Authentication

API Key (Header)

Bearer Token (OAuth)

Device Flow (CLI)

Request Format

Headers

Common Request Fields

Response Format

Success Response

Error Response

Rate Limiting

Error Codes

Common HTTP Status Codes

JSON-RPC Error Codes

Testing APIs

Using cURL

Using Postman

Using SDK

Choosing an API

API Clients

Common Workflows

Upload a Plugin

Call a Tool

Send Message to Agent

Next Steps