API reference

Automations

7 endpoints in this group.

Lists automations

GET/api/v1/automations

Scope
read
SDK method
listAutomations · list_automations
MCP tool
listAutomationsread-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/automations?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",
      "trigger": "string",
      "active": true,
      "run_count": 1,
      "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.

Creates an automation

POST/api/v1/automations

The automation starts disabled. Without trigger_config and steps the trigger's starter setup is used; whatever you send is validated with the same rules as the dashboard (400 automation_invalid). A webhook step's address must be public https. Needs admin permission. Scope: automations:write.

Scope
automations:write
SDK method
createAutomation · create_automation
MCP tool
createAutomation

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
triggerenumyesyeni_kisi | anahtar_kelime | etiket_eklendi | sessiz | miniapp_gonderim
trigger_configobjectno
stepsobject[]no

Example request

curl -X POST "https://hiboty.com/api/v1/automations" \
  -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":"Price question","trigger":"anahtar_kelime","trigger_config":{"kelimeler":["fiyat"],"eslesme":"icerir","aiBastir":true,"tekrarGun":0},"steps":[{"tur":"mesaj","metin":"We'\''ll share our price list right away."},{"tur":"devret"}]}'

Example response (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "trigger": "yeni_kisi",
    "trigger_config": {},
    "steps": [
      {}
    ],
    "active": true,
    "run_count": 1,
    "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).automation_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.

Automation details

GET/api/v1/automations/{id}

Returned with the trigger settings and steps. The member role only sees automations of bots it can access. Scope: automations:read.

Scope
automations:read
SDK method
getAutomation · get_automation
MCP tool
getAutomationread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X GET "https://hiboty.com/api/v1/automations/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",
    "trigger": "yeni_kisi",
    "trigger_config": {},
    "steps": [
      {}
    ],
    "active": true,
    "run_count": 1,
    "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.

Saves an automation

PUT/api/v1/automations/{id}

Replaces the name, trigger settings and all steps; the trigger type doesn't change. An invalid setup returns 400 automation_invalid. Turning it on or off is done with PATCH. Needs admin permission. Scope: automations:write.

Scope
automations:write
SDK method
saveAutomation · save_automation
MCP tool
saveAutomation

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Body fields

NameTypeRequiredDescription
namestringyeslen 2–60
trigger_configobjectyes
stepsobject[]yes

Example request

curl -X PUT "https://hiboty.com/api/v1/automations/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Price question","trigger_config":{"kelimeler":["fiyat"],"eslesme":"icerir","aiBastir":true,"tekrarGun":0},"steps":[{"tur":"mesaj","metin":"We'\''ll share our price list right away."},{"tur":"devret"}]}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "trigger": "yeni_kisi",
    "trigger_config": {},
    "steps": [
      {}
    ],
    "active": true,
    "run_count": 1,
    "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).automation_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.

Activates or stops an automation

PATCH/api/v1/automations/{id}

Activation runs the same validation as the dashboard; stopping also stops running executions. Scope: write.

Scope
write
SDK method
updateAutomation · update_automation
MCP tool
updateAutomationirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesAutomation ID

Body fields

NameTypeRequiredDescription
activebooleanyes

Example request

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

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "trigger": "string",
    "active": true,
    "run_count": 1,
    "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.

Deletes an automation

DELETE/api/v1/automations/{id}

The automation and its run history are permanently deleted. Needs admin permission. Scope: automations:write.

Scope
automations:write
SDK method
deleteAutomation · delete_automation
MCP tool
deleteAutomationirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X DELETE "https://hiboty.com/api/v1/automations/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.

Lists an automation's runs

GET/api/v1/automations/{id}/runs

Newest first: status, step, error, step log and contact ID. Error and log texts are returned in the language they were stored in (Turkish). The run context, which holds the contact's answers, isn't returned. Scope: automations:read.

Scope
automations:read
SDK method
listAutomationRuns · list_automation_runs
MCP tool
listAutomationRunsread-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/automations/3fa85f64-5717-4562-b3fc-2c963f66afa6/runs?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "contact_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "running",
      "step_index": 1,
      "error": "string",
      "log": [
        {
          "step": 1,
          "type": "string",
          "result": "string",
          "at": "string"
        }
      ],
      "next_run_at": "2026-11-06T09:00:00.000Z",
      "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.
  • 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.