---
title: AIxAI Developer Documentation — API, MCP server, CLI
description: AIxAI developer portal — REST API reference, MCP servers, NLWeb /ask, CLI, agent skills, authentication, versioning, rate limits, and every discovery document.
canonical: https://www.aixai.co.in/developers
last-updated: 2026-09-16
---

# AIxAI Developer Documentation

AIxAI is an AI consulting agency, so the public API surface is intentionally small: one unauthenticated write endpoint (submit a project inquiry) plus read surfaces for the service catalog and documentation. This is the canonical AIxAI developer portal, also reachable at `/docs` and `/api`.

## Authentication

None. No API keys, tokens, or signup. Abuse is bounded by per-IP rate limits. The full statement of what exists and what deliberately does not is in [/auth.md](/auth.md).

## REST API

| Endpoint | Auth | Purpose |
| --- | --- | --- |
| `POST /api/v1/send-email` | none | Submit a project inquiry (`submitContactInquiry`) |
| `POST /api/send-email` | none | Deprecated unversioned alias |

```bash
curl -X POST https://www.aixai.co.in/api/v1/send-email \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0f8c8a2e-1c4a-4a0d-9f6d-3a5a1b2c3d4e" \
  -d '{"name":"Ada Lovelace","email":"ada@example.com","message":"We want a RAG chatbot over our internal docs.","dryRun":true}'
```

### Sandbox / dry run

Send `"dryRun": true` in the body (or the header `X-Sandbox: true`) to validate a request end to end without delivering email. The MCP `submit_inquiry` tool takes the same flag. There is no separate sandbox host — the production endpoint simulates in place.

### Idempotency

Send an `Idempotency-Key` header on writes. A retry with the same key replays the first response and responds with `Idempotent-Replayed: true` instead of delivering a second email. Keys are honoured for 24 hours.

### Versioning and deprecation

Path versioning: `/api/v1/` is current. Breaking changes ship only in a new version path. Anything scheduled for removal carries `Deprecation` and `Sunset` headers at least 90 days in advance, announced here.

### Rate limits

10 requests/minute per IP on the inquiry endpoint, 30/minute on `/ask`, 60/minute on the MCP servers. Every response carries `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, and `RateLimit-Policy`; a 429 adds `Retry-After`.

### Errors

Always JSON, never HTML: `{"error": {"code", "message", "hint"}}`.

| HTTP | `error.code` | Meaning |
| --- | --- | --- |
| 400 | `validation_error` | Missing or invalid `name`, `email`, or `message` |
| 404 | `not_found` | No API endpoint at that path |
| 405 | `method_not_allowed` | Only POST is accepted |
| 429 | `rate_limited` | Over the limit; retry after `Retry-After` seconds |
| 500 | `delivery_failed` | Could not deliver; retry or email HQ@aixai.co.in |

## MCP servers

Two Streamable HTTP servers, no authentication.

- **Product** — `https://www.aixai.co.in/api/mcp` ([server card](/.well-known/mcp/server-card.json)). Tools: `list_services`, `get_service`, `search_services`, `submit_inquiry`. Resource: `aixai://services`.
- **Docs** — `https://www.aixai.co.in/api/mcp-docs` ([server card](/.well-known/mcp/docs-server-card.json)). Tools: `list_docs`, `get_doc`, `search_docs`. Resources: `aixai-docs://*`.

```json
{
  "mcpServers": {
    "aixai": { "type": "http", "url": "https://www.aixai.co.in/api/mcp" },
    "aixai-docs": { "type": "http", "url": "https://www.aixai.co.in/api/mcp-docs" }
  }
}
```

## NLWeb `/ask`

Natural-language query over the service catalog.

```bash
curl -s "https://www.aixai.co.in/ask?query=rag%20chatbot%20over%20internal%20docs"
curl -sN -H "Accept: text/event-stream" "https://www.aixai.co.in/ask?query=automation"
```

JSON responses carry `_meta` (`response_type`, `version`) and a `results` array of `{url, name, site, score, description, schema_object}`. Streaming emits `start`, `result`, and `complete` SSE events.

## CLI

```bash
npm install -g aixai-cli    # or: npx aixai-cli
aixai docs
aixai openapi
aixai contact --name "Ada Lovelace" --email ada@example.com --message "..."
```

Package metadata: https://registry.npmjs.org/aixai-cli · npm page: https://www.npmjs.com/package/aixai-cli

## Python SDK

```bash
pip install aixai-labs
```

```python
from aixai import AIxAI

client = AIxAI()
for service in client.iter_services():      # follows pagination for you
    print(service["slug"], service["title"])

client.submit_inquiry(name="Ada Lovelace", email="ada@example.com",
                      message="We want a RAG chatbot over our internal docs.",
                      dry_run=True)
```

No runtime dependencies, no API key. An `Idempotency-Key` is generated per call, and errors raise `ValidationError` / `RateLimitError` / `AIxAIError` carrying the API's `code`, `message` and `hint`. Package metadata: https://pypi.org/project/aixai-labs/

## Agent skills and plugin

- Skills index: [/.well-known/agent-skills/index.json](/.well-known/agent-skills/index.json) — `aixai-inquiry`, `aixai-agent-ready-site`.
- Install into a coding agent: `npx skills add vineetyad/AIxAI`
- Agent Plugin manifest: [plugin.json](https://github.com/vineetyad/AIxAI/blob/main/plugin.json) · MCP config: [mcp.json](https://github.com/vineetyad/AIxAI/blob/main/mcp.json)
- Repo conventions for coding agents: [AGENTS.md](https://github.com/vineetyad/AIxAI/blob/main/AGENTS.md)

## Discovery documents

| Document | Path |
| --- | --- |
| Agent guidance | [/llms.txt](/llms.txt), [/developers/llms.txt](/developers/llms.txt) |
| Agent view | [/agent.md](/agent.md) (also `/?mode=agent`) |
| OpenAPI 3.1 | [/openapi.json](/openapi.json) |
| API catalog (RFC 9727) | [/.well-known/api-catalog](/.well-known/api-catalog) |
| ARD catalog | [/.well-known/ard.json](/.well-known/ard.json), [/.well-known/ai-catalog.json](/.well-known/ai-catalog.json) |
| A2A agent card | [/.well-known/agent-card.json](/.well-known/agent-card.json) |
| MCP server cards | [product](/.well-known/mcp/server-card.json), [docs](/.well-known/mcp/docs-server-card.json) |
| Agent skills | [/.well-known/agent-skills/index.json](/.well-known/agent-skills/index.json) |
| Auth statement | [/auth.md](/auth.md) |
| Pricing | [/pricing.md](/pricing.md) |
| Sitemap / schema map | [/sitemap.xml](/sitemap.xml), [/schemamap.xml](/schemamap.xml) |

Every content page has a markdown twin at `<path>.md`, advertised with `rel="alternate"`, and the homepage also serves markdown via `Accept: text/markdown` or `?mode=agent`.

## Notes for agents

Submit inquiries only with the end user's consent and their real reply-to address — every non-dry-run call delivers a real email. Respect the rate-limit headers. If your use case needs webhooks or deeper integration, say so in an inquiry.