API reference

Every endpoint, parameter and response, generated from our OpenAPI 3.1 document.

Base URL: https://developers.vaxhost.com/api/v1
Version: 2026-05-01
Authentication: Authorization: Bearer <API key or access token> — Authentication
Format: JSON · Errors & pagination

Endpoints

GET /v1/me

Get the current account

Returns the profile of the user who owns the API key, or who authorised the OAuth access token.

Requires scope profile.read

Example request

curl "https://developers.vaxhost.com/api/v1/me" \
  -H "Authorization: Bearer $MITHILA_API_KEY"

Responses

200 The account.
401 Missing, invalid, expired or revoked credential.
403 The credential lacks the scope this endpoint needs.
429 Too many requests. Wait for Retry-After seconds.

Example response

{
    "data": {
        "id": "42",
        "name": "Sita Devi",
        "email": "sita@example.com",
        "email_verified": true,
        "phone_verified": true,
        "locale": "hi",
        "avatar_url": null,
        "created_at": "2026-05-01T10:00:00+05:30"
    },
    "meta": {
        "livemode": true
    }
}

GET /v1/apps

List Mithila apps

Public, enabled apps (marketplace, music, video, learning…) with their URLs. No credentials needed.

No credentials needed

Parameters

Name	In	Type	Description
`page`	query	integer = 1	Page number, from 1.
`per_page`	query	integer = 20	Items per page (1–100).

Example request

curl "https://developers.vaxhost.com/api/v1/apps?page=1&per_page=20"

Responses

200 A page of apps.
422 Invalid parameters.
429 Too many requests. Wait for Retry-After seconds.

Example response

{
    "data": [
        {
            "key": "music",
            "name": "Mithila Music",
            "short_name": "Music",
            "description": "Stream songs, albums and playlists from independent artists.",
            "url": "https://music.vaxhost.com/",
            "installable": true,
            "maintenance": false,
            "accent_color": "#E0177A",
            "icon": "https://music.vaxhost.com/icons/music/icon-192.png"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 20,
        "total": 10,
        "last_page": 1
    },
    "links": {
        "next": null,
        "prev": null
    }
}

GET /v1/status

API health

Use for uptime checks. Returns 503 when a dependency is down. No credentials needed.

No credentials needed

Example request

curl "https://developers.vaxhost.com/api/v1/status"

Responses

200 Healthy.
503 Degraded.

Example response

{
    "data": {
        "status": "ok",
        "api_version": "2026-05-01",
        "time": "2026-05-01T10:00:00+05:30",
        "components": {
            "api": "ok",
            "database": "ok"
        }
    }
}

GET /v1/categories

Active marketplace categories, parents before children. Build the tree with parent_id.

Requires scope catalog.read

Parameters

Name	In	Type	Description
`parent`	query	string	Only children of this category slug; `root` for top-level categories.
`page`	query	integer = 1	Page number, from 1.
`per_page`	query	integer = 100	Items per page (1–100).

Example request

curl "https://developers.vaxhost.com/api/v1/categories?page=1&per_page=20" \
  -H "Authorization: Bearer $MITHILA_API_KEY"

Responses

200 A page of categories.
401 Missing, invalid, expired or revoked credential.
403 The credential lacks the scope this endpoint needs.
429 Too many requests. Wait for Retry-After seconds.
422 Invalid parameters.

GET /v1/products

Search products

Active products from approved sellers. Prices are integer paise, GST inclusive.

Requires scope catalog.read

Parameters

Name	In	Type	Description
`q`	query	string	Search words.
`category`	query	string	Category slug (includes its sub-categories).
`seller`	query	string	Store slug.
`min_price`	query	integer	Minimum price in paise.
`max_price`	query	integer	Maximum price in paise.
`in_stock`	query	boolean	Only products in stock.
`sort`	query	string
`page`	query	integer = 1	Page number, from 1.
`per_page`	query	integer = 20	Items per page (1–100).

Example request

curl "https://developers.vaxhost.com/api/v1/products?page=1&per_page=20" \
  -H "Authorization: Bearer $MITHILA_API_KEY"

Responses

200 A page of products.
404 Not found (or not yours).
401 Missing, invalid, expired or revoked credential.
403 The credential lacks the scope this endpoint needs.
429 Too many requests. Wait for Retry-After seconds.
422 Invalid parameters.

GET /v1/products/{slug}

Get a product

One active product with images and variants.

Requires scope catalog.read

Parameters

Name	In	Type	Description
`slug`	path	string

Example request

curl "https://developers.vaxhost.com/api/v1/products/{slug}" \
  -H "Authorization: Bearer $MITHILA_API_KEY"

Responses

200 The product.
404 Not found (or not yours).
401 Missing, invalid, expired or revoked credential.
403 The credential lacks the scope this endpoint needs.
429 Too many requests. Wait for Retry-After seconds.

GET /v1/orders

List your orders

Orders the account placed as a customer, newest first.

Requires scope orders.read

Parameters

Name	In	Type	Description
`status`	query	string	Only orders in this status.
`page`	query	integer = 1	Page number, from 1.
`per_page`	query	integer = 20	Items per page (1–100).

Example request

curl "https://developers.vaxhost.com/api/v1/orders?page=1&per_page=20" \
  -H "Authorization: Bearer $MITHILA_API_KEY"

Responses

200 A page of orders.
401 Missing, invalid, expired or revoked credential.
403 The credential lacks the scope this endpoint needs.
429 Too many requests. Wait for Retry-After seconds.
422 Invalid parameters.

GET /v1/orders/{number}

Get one of your orders

Items, per-seller parts, shipment tracking and delivery address. 404 for orders of other accounts.

Requires scope orders.read

Parameters

Name	In	Type	Description
`number`	path	string	Order number, e.g. MTH-2605-00042.

Example request

curl "https://developers.vaxhost.com/api/v1/orders/{number}" \
  -H "Authorization: Bearer $MITHILA_API_KEY"

Responses

200 The order.
404 Not found (or not yours).
401 Missing, invalid, expired or revoked credential.
403 The credential lacks the scope this endpoint needs.
429 Too many requests. Wait for Retry-After seconds.

GET /v1/seller/orders

List your store's orders

Orders with the store the account owns, or works for with an orders role. Returns 403 not_a_seller for other accounts. The delivery address is included until the order is delivered or cancelled.

Requires scope seller.orders.read

Parameters

Name	In	Type	Description
`status`	query	string	Only orders in this status.
`page`	query	integer = 1	Page number, from 1.
`per_page`	query	integer = 20	Items per page (1–100).

Example request

curl "https://developers.vaxhost.com/api/v1/seller/orders?page=1&per_page=20" \
  -H "Authorization: Bearer $MITHILA_API_KEY"

Responses

200 A page of store orders.
401 Missing, invalid, expired or revoked credential.
403 The credential lacks the scope this endpoint needs.
429 Too many requests. Wait for Retry-After seconds.
422 Invalid parameters.

PATCH /v1/seller/orders/{id}/ship

Mark a store order shipped

Records the courier and AWB and moves a confirmed or packed order to shipped; the customer is notified. Needs a live key (test keys get 403 live_key_required). 409 invalid_state if the order cannot be shipped now.

Requires scope seller.orders.write

Parameters

Name	In	Type	Description
`id`	path	string	Store order id or number (the `id` or `number` of a SellerOrder).

Request body

Name	Type
`courier_name` required	string · max 100
`awb` required	string · max 64
`tracking_url`	string · max 500

Example request

curl -X PATCH "https://developers.vaxhost.com/api/v1/seller/orders/{id}/ship" \
  -H "Authorization: Bearer $MITHILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"courier_name":"India Post","awb":"EK123456789IN","tracking_url":"https://www.indiapost.gov.in/"}'

Responses

200 The shipped order.
404 Not found (or not yours).
409 The order is not in a state that can be shipped.
401 Missing, invalid, expired or revoked credential.
403 The credential lacks the scope this endpoint needs.
429 Too many requests. Wait for Retry-After seconds.
422 Invalid parameters.

Scopes

Scope	Description	Status
`profile.read`	Your name, email address, verification status and profile photo.	Available
`catalog.read`	Public product, category and seller information.	Available
`orders.read`	Your orders, their items, payment and shipping status.	Available
`seller.orders.read`	Orders placed with your Mithila store, including the delivery address while an order is being fulfilled.	Available
`seller.orders.write`	Mark your store's orders as shipped with the courier and tracking number.	Available

API reference

Endpoints

Get the current account

Example request

Responses

Example response

List Mithila apps

Parameters

Example request

Responses

Example response

API health

Example request

Responses

Example response

List categories

Parameters

Example request

Responses

Search products

Parameters

Example request

Responses

Get a product

Parameters

Example request

Responses

List your orders

Parameters

Example request

Responses

Get one of your orders

Parameters

Example request

Responses

List your store's orders

Parameters

Example request

Responses

Mark a store order shipped

Parameters

Request body

Example request

Responses

Scopes