API reference

Mini Apps

18 endpoints in this group.

Lists Mini Apps

GET/api/v1/miniapps

Scope
read
SDK method
listMiniApps · list_mini_apps
MCP tool
listMiniAppsread-only

Paginated

Parameters

NameTypeRequiredDescription
bot_idqueryuuidnoThis bot only
limitqueryintegernoPage size (1–200, default 100); 400 if it isn't an integerval 1–200, default 100
cursorquerystringnonext_cursor from the previous response (opaque; older date-time cursors are also accepted)

Example request

curl -X GET "https://hiboty.com/api/v1/miniapps?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty",
      "slug": "string",
      "template": "string",
      "status": "string",
      "url": "https://example.com/hook",
      "created_at": "2026-11-06T09:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Creates a Mini App

POST/api/v1/miniapps

It starts unpublished with the template's starter draft. The bot must be connected to its channel (409 not_connected). form_preset only applies to the form template. Needs admin permission. Scope: miniapps:write.

Scope
miniapps:write
SDK method
createMiniApp · create_mini_app
MCP tool
createMiniApp

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255

Body fields

NameTypeRequiredDescription
bot_iduuidyes
namestringyeslen 2–60
templateenumyeskatalog | form | baglanti
form_presetenumnoiletisim | randevu | anket | basvuru | bos

Example request

curl -X POST "https://hiboty.com/api/v1/miniapps" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"bot_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","name":"Booking form","template":"form","form_preset":"randevu"}'

Example response (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "slug": "string",
    "template": "katalog",
    "status": "draft",
    "url": "https://example.com/hook",
    "menu_button": true,
    "draft": {},
    "published_version": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "created_at": "2026-11-06T09:00:00.000Z"
    },
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.not_connected
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Mini App submissions and orders

GET/api/v1/miniapps/{id}/submissions

Scope
read
SDK method
listMiniAppSubmissions · list_mini_app_submissions
MCP tool
listMiniAppSubmissionsread-only

Paginated

Parameters

NameTypeRequiredDescription
idpathuuidyesMini App ID
kindqueryenumnoKind filter (randevu and iptal_talebi come from the AI request tools)form | order | randevu | iptal_talebi
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque; older date-time cursors are also accepted)

Example request

curl -X GET "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6/submissions?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "kind": "form",
      "status": "string",
      "contact_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "user_name": "string",
      "data": {},
      "source": "string",
      "created_at": "2026-11-06T09:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Order details

GET/api/v1/orders/{id}

The payment's delivery content and Telegram charge ID aren't returned. Scope: miniapps:read.

Scope
miniapps:read
SDK method
getOrder · get_order
MCP tool
getOrderread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X GET "https://hiboty.com/api/v1/orders/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "mini_app_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "mini_app_name": "string",
    "status": "yeni",
    "contact_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "user_name": "string",
    "data": {},
    "source": "string",
    "payment": {
      "status": "pending",
      "method": "telegram_stars",
      "currency": "USD",
      "amount": 1,
      "amount_stars": 1
    },
    "status_updated_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Changes the order status

PATCH/api/v1/orders/{id}

If notify is true the customer gets a status message through the bot; this also requires the messages:send scope. If the status changes but the notification can't be sent, the response is still 200 and data.notification holds { sent: false, error }. Scope: write.

Scope
write
SDK method
updateOrder · update_order
MCP tool
updateOrderexternal effect

Parameters

NameTypeRequiredDescription
idpathuuidyesOrder (submission) ID

Body fields

NameTypeRequiredDescription
statusenumyesyeni | hazirlaniyor | tamamlandi | iptal
notifybooleannodefault false

Example request

curl -X PATCH "https://hiboty.com/api/v1/orders/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"hazirlaniyor","notify":true}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "string",
    "notification": {
      "sent": false,
      "error": "string"
    }
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Mini App details

GET/api/v1/miniapps/{id}

Returned with the draft, published version and menu button state. The member role only sees apps of bots it can access. Scope: miniapps:read.

Scope
miniapps:read
SDK method
getMiniApp · get_mini_app
MCP tool
getMiniAppread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X GET "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "slug": "string",
    "template": "katalog",
    "status": "draft",
    "url": "https://example.com/hook",
    "menu_button": true,
    "draft": {},
    "published_version": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "created_at": "2026-11-06T09:00:00.000Z"
    },
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Updates the draft

PATCH/api/v1/miniapps/{id}

The published version doesn't change; your changes appear once you publish. config must match the template's schema, otherwise 400 miniapp_invalid is returned. Needs admin permission. Scope: miniapps:write.

Scope
miniapps:write
SDK method
updateMiniAppDraft · update_mini_app_draft
MCP tool
updateMiniAppDraft

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Body fields

NameTypeRequiredDescription
namestringnolen 2–60
configobjectno

Example request

curl -X PATCH "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Menu","config":{"baslik":"Menu","urunler":[{"id":"urun1","ad":"Coffee","fiyat":"90 USD"}]}}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "slug": "string",
    "template": "katalog",
    "status": "draft",
    "url": "https://example.com/hook",
    "menu_button": true,
    "draft": {},
    "published_version": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "created_at": "2026-11-06T09:00:00.000Z"
    },
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).miniapp_invalid
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Deletes a Mini App

DELETE/api/v1/miniapps/{id}

The app, its versions and its submissions are permanently deleted; if it's on the menu button, the Telegram menu returns to its default. Needs admin permission. Scope: miniapps:write.

Scope
miniapps:write
SDK method
deleteMiniApp · delete_mini_app
MCP tool
deleteMiniAppexternal effectirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X DELETE "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deleted": true
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Publishes the draft

POST/api/v1/miniapps/{id}/publish

A new immutable version is created from the draft and goes public; if publish approval is on, the version waits for approval and the live version doesn't change. If the plan doesn't include Mini Apps it returns 403 plan_limit; an invalid draft returns 400 miniapp_invalid. Needs admin permission. Scope: miniapps:write.

Scope
miniapps:write
SDK method
publishMiniApp · publish_mini_app
MCP tool
publishMiniAppexternal effect

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathuuidyesID
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255

Example request

curl -X POST "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6/publish" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "slug": "string",
    "template": "katalog",
    "status": "draft",
    "url": "https://example.com/hook",
    "menu_button": true,
    "draft": {},
    "published_version": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "created_at": "2026-11-06T09:00:00.000Z"
    },
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).miniapp_invalid
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.plan_limit
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Unpublishes the app

POST/api/v1/miniapps/{id}/unpublish

The public page closes; if it's on the menu button, the Telegram menu returns to its default. Versions aren't deleted. Needs admin permission. Scope: miniapps:write.

Scope
miniapps:write
SDK method
unpublishMiniApp · unpublish_mini_app
MCP tool
unpublishMiniAppexternal effect

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathuuidyesID
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255

Example request

curl -X POST "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6/unpublish" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "slug": "string",
    "template": "katalog",
    "status": "draft",
    "url": "https://example.com/hook",
    "menu_button": true,
    "draft": {},
    "published_version": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "created_at": "2026-11-06T09:00:00.000Z"
    },
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Rolls back to an earlier version

POST/api/v1/miniapps/{id}/rollback

The given version goes live again and the draft doesn't change. If the plan doesn't include Mini Apps it returns 403 plan_limit; a version from another app returns 404. Needs admin permission. Scope: miniapps:write.

Scope
miniapps:write
SDK method
rollbackMiniApp · rollback_mini_app
MCP tool
rollbackMiniAppexternal effect

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathuuidyesID
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255

Body fields

NameTypeRequiredDescription
version_iduuidyes

Example request

curl -X POST "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6/rollback" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"version_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "slug": "string",
    "template": "katalog",
    "status": "draft",
    "url": "https://example.com/hook",
    "menu_button": true,
    "draft": {},
    "published_version": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "created_at": "2026-11-06T09:00:00.000Z"
    },
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.plan_limit
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Sets the Telegram menu button

POST/api/v1/miniapps/{id}/menu-button

enabled: true points the bot's menu button at this app (it must be published); false returns it to the default. A bot has one menu button. Returns 409 if the app isn't published or the bot isn't connected, and 502 if Telegram rejects it. Needs admin permission. Scope: miniapps:write.

Scope
miniapps:write
SDK method
setMiniAppMenuButton · set_mini_app_menu_button
MCP tool
setMiniAppMenuButtonexternal effect

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathuuidyesID
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255

Body fields

NameTypeRequiredDescription
enabledbooleanyes

Example request

curl -X POST "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6/menu-button" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "slug": "string",
    "template": "katalog",
    "status": "draft",
    "url": "https://example.com/hook",
    "menu_button": true,
    "draft": {},
    "published_version": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "created_at": "2026-11-06T09:00:00.000Z"
    },
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
  • 502A channel or external service failed (channel_error).

Lists versions

GET/api/v1/miniapps/{id}/versions

Versions, newest first. Versions awaiting publish approval or rejected are marked by the status field. Scope: miniapps:read.

Scope
miniapps:read
SDK method
listMiniAppVersions · list_mini_app_versions
MCP tool
listMiniAppVersionsread-only

Paginated

Parameters

NameTypeRequiredDescription
idpathuuidyesID
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque)

Example request

curl -X GET "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6/versions?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "is_published": true,
      "created_at": "2026-11-06T09:00:00.000Z",
      "config_sha256": "string",
      "status": "published"
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Draft preview

GET/api/v1/miniapps/{id}/preview

Returns a signed address showing the draft, valid for 2 hours, and the draft configuration. Only share the address with people you trust. If the draft is invalid, valid is false and errors is filled in. Scope: miniapps:read.

Scope
miniapps:read
SDK method
getMiniAppPreview · get_mini_app_preview
MCP tool
getMiniAppPreviewread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X GET "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6/preview" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "url": "https://example.com/hook",
    "expires_at": "2026-11-06T09:00:00.000Z",
    "valid": true,
    "errors": [
      "string"
    ],
    "config": {}
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Lists orders

GET/api/v1/orders

Newest first. The member role only sees orders of bots it can access. Telegram Stars refunds aren't in the API: they're an irreversible money movement, so they're done in the dashboard. Scope: miniapps:read.

Scope
miniapps:read
SDK method
listOrders · list_orders
MCP tool
listOrdersread-only

Paginated

Parameters

NameTypeRequiredDescription
statusqueryenumnoOrder statusyeni | hazirlaniyor | tamamlandi | iptal
app_idqueryuuidnoThis Mini App only
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque)

Example request

curl -X GET "https://hiboty.com/api/v1/orders?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "mini_app_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "mini_app_name": "string",
      "status": "yeni",
      "contact_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "user_name": "string",
      "data": {},
      "source": "string",
      "payment": {
        "status": "pending",
        "method": "telegram_stars",
        "currency": "USD",
        "amount": 1,
        "amount_stars": 1
      },
      "status_updated_at": "2026-11-06T09:00:00.000Z",
      "created_at": "2026-11-06T09:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Imports a product feed into the catalog

POST/api/v1/miniapps/{id}/feed-import

Imports a Google Merchant XML/RSS, CSV or JSON feed into the draft of a catalog Mini App; send either url or content. The first 50 products are taken and the rest are reported in warnings; Stars prices and delivery content of products with the same ID are kept. The published version doesn't change; publishing is manual. With dry_run true only a preview is returned. With auto_refresh true the address is stored and the draft is refreshed once a day. With ai_knowledge true the catalog is also written to the bot's AI knowledge. The address must be public; internal network addresses return 400 feed_invalid. At most 30 requests per hour. Needs admin permission. Scope: miniapps:write.

Scope
miniapps:write
SDK method
importMiniAppFeed · import_mini_app_feed
MCP tool
importMiniAppFeedexternal effectirreversible

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathuuidyesID
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255

Body fields

NameTypeRequiredDescription
urlstringnoPublic http/https feed addresslen ≤ 2000
contentstringnoThe feed itself (file content)len ≤ 2000000
formatenumnoDetected from the content when omittedxml | csv | json
dry_runbooleanno
auto_refreshbooleanno
ai_knowledgebooleanno

Example request

curl -X POST "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6/feed-import" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://shop.example.com/feeds/google.xml","dry_run":false,"auto_refresh":true,"ai_knowledge":true}'

Example response (200)

JSON
{
  "data": {
    "saved": true,
    "format": "xml",
    "mapping": {
      "id": "string",
      "ad": "string",
      "aciklama": "string",
      "fiyat": "string",
      "gorsel": "string",
      "stok": "string"
    },
    "total": 1,
    "imported": 1,
    "warnings": [
      {
        "code": "kesildi",
        "count": 1,
        "message": "string"
      }
    ],
    "products": [
      {
        "id": "string",
        "name": "Hiboty",
        "price": "string",
        "image_url": "https://example.com/a.png"
      }
    ],
    "feed": {
      "url": "https://example.com/hook",
      "auto_refresh": true,
      "ai_knowledge": true,
      "synced_at": "2026-11-06T09:00:00.000Z",
      "checked_at": "2026-11-06T09:00:00.000Z",
      "error": "string"
    }
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).feed_invalid
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Publishes a Mini App version awaiting approval

POST/api/v1/miniapps/{id}/versions/{version_id}/approve

The content fingerprint (config_sha256) is checked and the version goes live; if it doesn't match, 409 integrity is returned. If the plan doesn't include Mini Apps it returns 403 plan_limit. Needs admin permission. With four-eyes on, the person who made the change can't approve it (403 four_eyes); approval isn't possible with an API key. Scope: miniapps:write.

Scope
miniapps:write
SDK method
approveMiniAppVersion · approve_mini_app_version
MCP tool
approveMiniAppVersionexternal effect

Parameters

NameTypeRequiredDescription
idpathuuidyesID
version_idpathuuidyesversion_id

Example request

curl -X POST "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6/versions/3fa85f64-5717-4562-b3fc-2c963f66afa6/approve" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "slug": "string",
    "template": "katalog",
    "status": "draft",
    "url": "https://example.com/hook",
    "menu_button": true,
    "draft": {},
    "published_version": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "created_at": "2026-11-06T09:00:00.000Z"
    },
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.plan_limitfour_eyes
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.integrity
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Rejects a Mini App version awaiting approval

POST/api/v1/miniapps/{id}/versions/{version_id}/reject

The version doesn't go live; an admin or the person who requested the publish can reject it. Scope: miniapps:write.

Scope
miniapps:write
SDK method
rejectMiniAppVersion · reject_mini_app_version
MCP tool
rejectMiniAppVersion

Parameters

NameTypeRequiredDescription
idpathuuidyesID
version_idpathuuidyesversion_id

Example request

curl -X POST "https://hiboty.com/api/v1/miniapps/3fa85f64-5717-4562-b3fc-2c963f66afa6/versions/3fa85f64-5717-4562-b3fc-2c963f66afa6/reject" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "slug": "string",
    "template": "katalog",
    "status": "draft",
    "url": "https://example.com/hook",
    "menu_button": true,
    "draft": {},
    "published_version": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "config": {},
      "created_at": "2026-11-06T09:00:00.000Z"
    },
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.