Skip to main content
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

ServiceHostPurpose
REST APIapi.noorle.comAdministrative operations (plugins, agents, configurations)
MCP Gatewaymcp-{id}.noorle.comModel Context Protocol for LLM tool access
Agent Gatewayagent-{id}.noorle.comAgent-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

CodeMeaningAction
200OKSuccess
201CreatedResource created
400Bad RequestFix your request
401UnauthorizedCheck authentication
403ForbiddenInsufficient permissions
404Not FoundResource doesn’t exist
429Too Many RequestsWait before retrying
500Internal ErrorServer error, retry later
Error Reference →

​
JSON-RPC Error Codes

MCP and A2A use JSON-RPC 2.0 error codes: 
{
  "code": -32700,
  "message": "Parse error"
}
CodeMessageMeaning
-32700Parse errorInvalid JSON
-32600Invalid RequestBad method/params
-32601Method not foundMethod doesn’t exist
-32602Invalid paramsWrong parameters
-32603Internal errorServer 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

  1. Import OpenAPI spec from https://api.noorle.com/openapi.json
  2. Set X-API-Key header in collection
  3. 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

1. Build locally: noorle plugin build
2. POST to /v1/capabilities/upload
3. Get capability_id and active_version
4. Plugin available immediately

​
Call a Tool

1. Connect to MCP gateway
2. Call tools/list to discover tools
3. Call tools/call with tool name and parameters
4. Get result

​
Send Message to Agent

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

​
Next Steps