Documentation Index
Fetch the complete documentation index at: https://noorle.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
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"
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"
}
]
}
}
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"
}
}
Authentication
All APIs support multiple authentication methods:
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
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
}
Success Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"tools": [...],
"resources": [...]
}
}
Error Response
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32603,
"message": "Internal error",
"data": {
"details": "Something went wrong"
}
}
}
Rate Limiting
All APIs implement rate limiting:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1711123200
{
"error": {
"code": 429,
"message": "Too many requests"
}
}
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 |
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
1. Build locally: noorle plugin build
2. POST to /v1/capabilities/upload
3. Get capability_id and active_version
4. Plugin available immediately
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
