API reference

Media

4 endpoints in this group.

Lists the media library

GET/api/v1/media

Newest first; q searches the display name. Needs admin permission. Scope: organization:read.

Scope
organization:read
SDK method
listMedia · list_media
MCP tool
listMediaread-only

Paginated

Parameters

NameTypeRequiredDescription
qquerystringnoSearch in the display name
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/media?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "url": "https://example.com/hook",
      "path": "string",
      "name": "Hiboty",
      "mime": "string",
      "size": 1,
      "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.

Uploads an image

POST/api/v1/media

Up to 2 MB; JPG, PNG, WebP or GIF (the type is read from the file content; SVG isn't accepted). Up to 500 images per organization (409 limit_reached); the total size can't exceed the plan's storage quota (413 storage_quota_exceeded; usage is in the storage field of getUsage); 30 uploads per minute (429). Needs admin permission. Scope: organization:write.

Scope
organization:write
SDK method
uploadMedia · upload_media
MCP tool
uploadMedia

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
file_namestringyeslen ≤ 255
file_base64stringyesThe file's base64 content (without a data: prefix)

Example request

curl -X POST "https://hiboty.com/api/v1/media" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"file_name":"logo.png","file_base64":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="}'

Example response (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://example.com/hook",
    "path": "string",
    "name": "Hiboty",
    "mime": "string",
    "size": 1,
    "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.
  • 409The action isn't possible in this state; the code gives the reason.limit_reached
  • 413The plan's storage quota is full (storage_quota_exceeded); delete images or upgrade the plan.storage_quota_exceeded
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Gets where an image is used

GET/api/v1/media/{id}/usage

Checks campaigns, scheduled posts, the brand logo, Mini Apps, automations and conversation history. Needs admin permission. Scope: organization:read.

Scope
organization:read
SDK method
getMediaUsage · get_media_usage
MCP tool
getMediaUsageread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

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

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "in_use": true,
    "usages": [
      {
        "place": "campaign",
        "count": 1
      }
    ]
  }
}

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 image

DELETE/api/v1/media/{id}

An image in use can't be deleted (409 media_in_use). The file is permanently deleted too. Needs admin permission. Scope: organization:write.

Scope
organization:write
SDK method
deleteMedia · delete_media
MCP tool
deleteMediairreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X DELETE "https://hiboty.com/api/v1/media/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).
  • 409The action isn't possible in this state; the code gives the reason.media_in_use
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.