> ## 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.

# API Overview

> Noorle's three APIs at a glance: REST at api.noorle.com for admin, MCP gateways for LLM tools, and A2A gateways for agent-to-agent messaging

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:**

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

[REST API Reference →](/docs/reference/rest/capabilities-list)

### 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:**

```json theme={null}
// 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 →](/docs/reference/mcp/overview)

### 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:**

```json theme={null}
// 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 →](/docs/reference/a2a/overview)

## Authentication

All APIs support multiple authentication methods:

### API Key (Header)

```bash theme={null}
curl -H "X-API-Key: ak-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4s9t0u1v2w3x4y5z6" \
  https://api.noorle.com/v1/capabilities
```

### Bearer Token (OAuth)

```bash theme={null}
curl -H "Authorization: Bearer eyJhbGc..." \
  https://api.noorle.com/v1/agents
```

### Device Flow (CLI)

```bash theme={null}
noorle login
# Prompts with verification URL and code
# Exchanges device code for OAuth token
```

[Authentication Guide →](/docs/reference/authentication)

## 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

```json theme={null}
{
  "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

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [...],
    "resources": [...]
  }
}
```

HTTP Status: **200 OK**

### Error Response

```json theme={null}
{
  "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:

```json theme={null}
{
  "error": {
    "code": 429,
    "message": "Too many requests"
  }
}
```

Wait until `X-RateLimit-Reset` timestamp before retrying.

[Rate Limits →](/docs/reference/errors-and-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 →](/docs/reference/errors-and-rate-limits)

## JSON-RPC Error Codes

MCP and A2A use JSON-RPC 2.0 error codes:

```json theme={null}
{
  "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

```bash theme={null}
# 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`

```typescript theme={null}
import { NoorleClient } from "@noorle/sdk";

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

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

## Choosing an API

```mermaid theme={null}
graph TD
    A["What do you need?"]
    B["Manage Plugins/Agents"]
    C["Interact with Agents"]
    D["REST API<br/>v1/capabilities<br/>v1/agents<br/>v1/plugins<br/><br/>Use for:<br/>• CLI tools<br/>• Admin dashboards<br/>• Plugin uploads"]
    E["Choose transport"]
    F["Single query?<br/>A2A /message/send"]
    G["Streaming?<br/>A2A /message/stream"]
    H["Tool discovery?<br/>MCP tools/list"]

    A --> B
    A --> C
    B --> D
    C --> E
    E --> F
    E --> G
    E --> H
```

## 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

* [Authentication Methods](/docs/reference/authentication)
* [REST API Reference](/docs/reference/rest/capabilities-list)
* [MCP Protocol](/docs/reference/mcp/overview)
* [A2A Protocol](/docs/reference/a2a/overview)
* [Error Handling](/docs/reference/errors-and-rate-limits)