API reference

Custom Mini Apps

6 endpoints in this group.

Lists custom Mini App requests

GET/api/v1/custom-miniapps

Newest first. The quote and links are returned at the stages they appear in the dashboard. Scope: miniapps:read.

Scope
miniapps:read
SDK method
listCustomMiniAppRequests · list_custom_mini_app_requests
MCP tool
listCustomMiniAppRequestsread-only

Paginated

Parameters

NameTypeRequiredDescription
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/custom-miniapps?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "yeni",
      "title": "Example",
      "description": "string",
      "examples": "string",
      "budget": "string",
      "takes_payment": true,
      "handles_personal_data": true,
      "quote_amount_cents": 1,
      "monthly_amount_cents": 1,
      "delivery_days": 1,
      "quote_note": "string",
      "payment_url": "https://example.com/a.png",
      "preview_url": "https://example.com/a.png",
      "delivery_url": "https://example.com/a.png",
      "created_at": "2026-11-06T09:00:00.000Z",
      "updated_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.

Opens a custom Mini App request

POST/api/v1/custom-miniapps

The request goes to the Hiboty team, who prepare the quote. At most 5 requests per hour (429); if the open request limit is full it returns 409 open_limit. Needs admin permission. Scope: miniapps:write.

Scope
miniapps:write
SDK method
createCustomMiniAppRequest · create_custom_mini_app_request
MCP tool
createCustomMiniAppRequestexternal effect

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
titlestringyeslen 3–120
descriptionstringyeslen 30–4000
examplesstringnolen ≤ 1000
budgetstringnolen ≤ 60
takes_paymentbooleanno
handles_personal_databooleanno

Example request

curl -X POST "https://hiboty.com/api/v1/custom-miniapps" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"title":"Booking app","description":"We want an app where customers can pick a service and book, and that sends reminders.","budget":"500 USD","takes_payment":false,"handles_personal_data":true}'

Example response (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "yeni",
    "title": "Example",
    "description": "string",
    "examples": "string",
    "budget": "string",
    "takes_payment": true,
    "handles_personal_data": true,
    "quote_amount_cents": 1,
    "monthly_amount_cents": 1,
    "delivery_days": 1,
    "quote_note": "string",
    "payment_url": "https://example.com/a.png",
    "preview_url": "https://example.com/a.png",
    "delivery_url": "https://example.com/a.png",
    "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.
  • 409The action isn't possible in this state; the code gives the reason.open_limit
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Custom Mini App request details

GET/api/v1/custom-miniapps/{id}

Only this organization's requests are visible; the team's internal notes aren't returned. Scope: miniapps:read.

Scope
miniapps:read
SDK method
getCustomMiniAppRequest · get_custom_mini_app_request
MCP tool
getCustomMiniAppRequestread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

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

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "yeni",
    "title": "Example",
    "description": "string",
    "examples": "string",
    "budget": "string",
    "takes_payment": true,
    "handles_personal_data": true,
    "quote_amount_cents": 1,
    "monthly_amount_cents": 1,
    "delivery_days": 1,
    "quote_note": "string",
    "payment_url": "https://example.com/a.png",
    "preview_url": "https://example.com/a.png",
    "delivery_url": "https://example.com/a.png",
    "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.

Accepts the quote

POST/api/v1/custom-miniapps/{id}/accept

Only valid at the quote stage; otherwise it returns 409 invalid_status. After acceptance the payment link is sent and cancellation goes through the team. Needs admin permission. Scope: miniapps:write.

Scope
miniapps:write
SDK method
acceptCustomMiniAppQuote · accept_custom_mini_app_quote
MCP tool
acceptCustomMiniAppQuoteexternal 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

Example request

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

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "yeni",
    "title": "Example",
    "description": "string",
    "examples": "string",
    "budget": "string",
    "takes_payment": true,
    "handles_personal_data": true,
    "quote_amount_cents": 1,
    "monthly_amount_cents": 1,
    "delivery_days": 1,
    "quote_note": "string",
    "payment_url": "https://example.com/a.png",
    "preview_url": "https://example.com/a.png",
    "delivery_url": "https://example.com/a.png",
    "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.invalid_status
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Approves the preview

POST/api/v1/custom-miniapps/{id}/approve-preview

Only valid at the preview stage; otherwise it returns 409 invalid_status. Needs admin permission. Scope: miniapps:write.

Scope
miniapps:write
SDK method
approveCustomMiniAppPreview · approve_custom_mini_app_preview
MCP tool
approveCustomMiniAppPreviewexternal 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

Example request

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

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "yeni",
    "title": "Example",
    "description": "string",
    "examples": "string",
    "budget": "string",
    "takes_payment": true,
    "handles_personal_data": true,
    "quote_amount_cents": 1,
    "monthly_amount_cents": 1,
    "delivery_days": 1,
    "quote_note": "string",
    "payment_url": "https://example.com/a.png",
    "preview_url": "https://example.com/a.png",
    "delivery_url": "https://example.com/a.png",
    "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.invalid_status
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Cancels the request

POST/api/v1/custom-miniapps/{id}/cancel

Valid until the quote is accepted; otherwise it returns 409 invalid_status. Needs admin permission. Scope: miniapps:write.

Scope
miniapps:write
SDK method
cancelCustomMiniAppRequest · cancel_custom_mini_app_request
MCP tool
cancelCustomMiniAppRequestexternal 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

Example request

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

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "yeni",
    "title": "Example",
    "description": "string",
    "examples": "string",
    "budget": "string",
    "takes_payment": true,
    "handles_personal_data": true,
    "quote_amount_cents": 1,
    "monthly_amount_cents": 1,
    "delivery_days": 1,
    "quote_note": "string",
    "payment_url": "https://example.com/a.png",
    "preview_url": "https://example.com/a.png",
    "delivery_url": "https://example.com/a.png",
    "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.invalid_status
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.