# Karigarh for developers

Karigarh publishes its handicrafts catalogue through a small, read-only HTTP
API. It is free to use, needs **no API key and no account**, and returns JSON.
Use it to look up products, prices in Indian Rupees, stock availability,
materials, ODOP districts and the category taxonomy. Carts, checkout,
payments, orders and accounts are not part of the public API: those steps are
completed by a person on the website.

## Base URL

- Production: `https://api.karigarh.com`
- The catalogue endpoints (`/api/v1/Product/…`, `/api/v1/category/…`,
  `/api/v1/subcategory/…`) are also reachable on `https://www.karigarh.com`.
  Everyone calling through the storefront shares one rate-limit budget, so
  prefer the production host for anything beyond a quick test.

The machine-readable description is the OpenAPI 3.1 document at
[/openapi.json](https://www.karigarh.com/openapi.json). It is also listed in
the API catalog at
[/.well-known/api-catalog](https://www.karigarh.com/.well-known/api-catalog).

## Quickstart

List the five newest products:

```bash
curl "https://api.karigarh.com/api/v1/Product/products?approved=true&limit=5&sort=newest"
```

Search the catalogue by keyword:

```bash
curl "https://api.karigarh.com/api/v1/Product/searchproduct?query=blue%20pottery"
```

Fetch one product by its slug (the last part of its URL on the site):

```bash
curl "https://api.karigarh.com/api/v1/Product/product?slug=<product-slug>"
```

Or use the command-line tool, which needs Node.js 18 or later:

```bash
npx karigarh-cli search "blue pottery"
npx karigarh-cli products --odop --limit 10
npx karigarh-cli product <product-slug> --json
```

## MCP server

AI assistants that speak the Model Context Protocol can use the catalogue
directly. Point any MCP client at:

```text
https://www.karigarh.com/mcp
```

It uses the Streamable HTTP transport, needs no authentication, and is
read-only. Tools:

| Tool | What it does |
| --- | --- |
| `search_products` | Keyword search, returns products with price, stock and URL |
| `list_products` | Browse or filter by ODOP district, state or category, sorted by newest, best-selling or price |
| `get_product` | Full details of one product by slug |
| `list_categories` | Craft categories, optionally with subcategories |
| `list_odop_districts` | Districts with ODOP items |

Machine-readable descriptions: the server card at
[/mcp/server-card](https://www.karigarh.com/mcp/server-card) and registry
metadata at [/server.json](https://www.karigarh.com/server.json).

## Authentication and keys

None. Every endpoint below is public and read-only, so there are no API keys
to request and nothing to sign. Please send an honest `User-Agent` that names
your application.

## Sandbox

There is no separate sandbox environment, and none is needed: the public API
cannot create, change or delete anything, so it is safe to call the
production host while you develop. Data is live, so prices and stock can
change between calls.

## Endpoints

| Method and path | What it returns |
| --- | --- |
| `GET /api/v1/Product/products` | Listed products. Filters: `limit` (max 50), `sort` (`newest`, `bestselling`, `price_asc`, `price_desc`), `isOdop=true`, `odopDistrict`, `state`, `categories`. |
| `GET /api/v1/Product/product?slug=` | One product by slug (or `?id=`). 404 when it is not publicly listed. |
| `GET /api/v1/Product/searchproduct?query=` | Keyword search over titles and descriptions. |
| `GET /api/v1/Product/odop-districts` | Districts that have ODOP (One District One Product) items. |
| `GET /api/v1/category/allcategory` | The category taxonomy. |
| `GET /api/v1/subcategory/allcategory` | Subcategories. |

All prices are in Indian Rupees and include GST. Shipping is within India
only.

## Rate limits

The catalogue endpoints allow **600 requests per 15 minutes per IP address**.
Every response tells you where you stand, so you can slow down before you are
refused:

| Header | Example | Meaning |
| --- | --- | --- |
| `RateLimit-Limit` | `600` | Requests allowed in the window |
| `RateLimit-Remaining` | `598` | Requests left in the window |
| `RateLimit-Reset` | `840` | Seconds until the window resets |
| `RateLimit-Policy` | `600;w=900` | Quota and window length in seconds |
| `RateLimit` | `"catalog"; r=598; t=840` | Same state as a structured field (IETF draft-8) |
| `X-RateLimit-Limit`, `X-RateLimit-Remaining` | `600`, `598` | Legacy equivalents |

When the budget is spent the API answers `429 Too Many Requests` with a
`Retry-After` header giving the seconds to wait. For bulk work, read the
product feed described below instead of walking the listing endpoint.

## Errors

Every error is JSON, never an HTML page, with a stable code you can branch on:

```json
{
  "success": false,
  "message": "Product not found",
  "error": {
    "code": "NOT_FOUND",
    "message": "Product not found",
    "hint": "Check the path and HTTP method against the OpenAPI description.",
    "docs": [
      "https://www.karigarh.com/developers",
      "https://www.karigarh.com/openapi.json"
    ]
  }
}
```

| Status | `error.code` | When |
| --- | --- | --- |
| 400 | `BAD_REQUEST` or `VALIDATION_ERROR` | A parameter or body is malformed |
| 404 | `NOT_FOUND` | Unknown path, or a product that is not publicly listed |
| 429 | `RATE_LIMITED` | Rate limit reached; wait for `Retry-After` |
| 500 | `INTERNAL_ERROR` | A problem on our side; retry later |

## Versioning and deprecation

- The API is versioned in the URL path. Everything documented here is
  `/api/v1`, and `v1` only receives backwards-compatible changes: new
  endpoints, new optional parameters and new response fields. Ignore fields
  you do not recognise.
- A breaking change ships as a new major version (`/api/v2`) alongside the
  old one; `v1` is not changed in place.
- An endpoint that is going away is announced here first and then marked on
  every response with the `Deprecation` header (RFC 9745) and, once a
  removal date is set, the `Sunset` header (RFC 8594), plus a
  `Link: <https://www.karigarh.com/developers>; rel="deprecation"` header.
- A deprecated endpoint keeps working for at least 6 months after the
  `Deprecation` header first appears.
- No endpoint is currently deprecated.

## Bulk data and other machine-readable files

- [/feeds/products.jsonl](https://www.karigarh.com/feeds/products.jsonl): every
  listed product as a schema.org `Product`, one per line, refreshed on every
  deployment. The best source for bulk reads.
- [/llms.txt](https://www.karigarh.com/llms.txt): an index of the site for
  language models.
- [/agents.md](https://www.karigarh.com/agents.md): when an AI agent should
  use Karigarh, and how.
- [/sitemap.xml](https://www.karigarh.com/sitemap.xml): every indexable URL.
- Any content page is available as markdown: send `Accept: text/markdown`, or
  append `.md` to the path, for example
  [/AboutUs.md](https://www.karigarh.com/AboutUs.md).

## Terms and support

Use of the API is covered by the
[terms and conditions](https://www.karigarh.com/TermsCondition). When you show
Karigarh data to people, link to the product page, because prices and stock
change. Questions about the API go to **support@enewbharat.com**, 9:00 AM to
5:00 PM (IST), Monday to Saturday.