Agent API action response format — general

9 min readGuide reference date: October 14, 2026.View original in Notion ↗

Purpose

This document defines a recommended JSON format for structured data returned by external servers through API Action, so the chatbot can use it to answer.

External servers (your backend) may still return arbitrary JSON and are not required to follow this format.

However, following this format helps the chatbot understand responses reliably and can improve answer accuracy and quality.

This is a general API result format for interpreting responses and generating natural-language answers, not the visual card format (sidetalk.card.v1).

Overview

Response structure (top level)

The top level should include the schema version, success status, and actual data.

Field	Type	Required	Description
schema	String	Yes	Identifies the protocol version. Use the fixed value "sidetalk.api-result.v1".
success	Boolean	Yes	Whether request processing succeeded.
data	Object	Conditional	The actual data included in a success response.
summary	String	No	A one-line summary of the response. Optional, but helps the chatbot understand the content faster.
error	Object	Conditional	Error information included in a failure response.
meta	Object	No	Additional information such as source, pagination, and status code.

Basic rules

This is a recommended structure; arbitrary JSON responses can also be used.

Follow the structure below when possible so the chatbot can understand responses more reliably.

The examples are illustrative. Design the structure inside data freely to suit your API’s purpose.
Include schema and success in all responses when possible.
With success: true, include data.
With success: false, include error.
summary is optional, but helps the chatbot understand the response faster.
Include meta only when needed.
data has no fixed schema; include only information needed for the answer.
Arbitrary JSON responses remain supported, but a clear common structure can improve AI response quality.

The recommended success structure is:

JSON

{
  "schema": "sidetalk.api-result.v1",
  "success": true,
  "data": {}
}

The recommended failure structure is:

JSON

{
  "schema": "sidetalk.api-result.v1",
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "오류 메시지"
  }
}

Nested object specifications

1. Error object

A common object used when requests fail.

Field	Type	Required	Description
code	String	Yes	The error code. Examples: "NOT_FOUND", "INVALID_PARAMETER"
message	String	Yes	Text describing the error.
detail	String	No	A more detailed error description.

2. Meta object

An optional object for additional information.

Field	Type	Required	Description
source	String	No	The data source. Examples: "public_api", "internal_api"
page	Number	No	The current page number.
totalCount	Number	No	The total number of records.
statusCode	Number	No	The original API’s HTTP status code.

How to write the data field

This document does not enforce a fixed nested structure for data.

The examples are illustrative; include only information appropriate to your API’s purpose.

For example, you can structure it freely in these ways.

List data: items, count
Single record: item
Status information: status
Key domain information for reservations, orders, products, etc.
Values directly needed for chatbot answers

Avoid unnecessarily deep nesting in data. Use a simple structure with clearly named fields so the chatbot can understand it immediately.

Example:

name
status
address
date
time
count
items

Example responses (JSON)

1) Success — list data

JSON

{
  "schema": "sidetalk.api-result.v1",
  "success": true,
  "summary": "검색 결과 3건",
  "data": {
    "items": [
      {
        "name": "서울지점",
        "status": "영업중",
        "address": "서울특별시 강남구 테헤란로 123"
      },
      {
        "name": "부산지점",
        "status": "영업중",
        "address": "부산광역시 해운대구 센텀로 45"
      },
      {
        "name": "대구지점",
        "status": "휴무",
        "address": "대구광역시 수성구 동대구로 88"
      }
    ],
    "count": 3
  },
  "meta": {
    "source": "public_api",
    "statusCode": 200
  }
}

2) Success — single record

JSON

{
  "schema": "sidetalk.api-result.v1",
  "success": true,
  "summary": "예약 정보를 찾았습니다.",
  "data": {
    "item": {
      "reservationNo": "RSV-20260702-ABCD12",
      "name": "홍길동",
      "date": "2026-07-05",
      "time": "14:00",
      "status": "예약완료"
    }
  }
}

3) Success — summary-focused data

JSON

{
  "schema": "sidetalk.api-result.v1",
  "success": true,
  "summary": "오늘 주문은 총 2건입니다.",
  "data": {
    "count": 2,
    "items": [
      {
        "orderNo": "20260702-1001",
        "productName": "보물상자 A",
        "status": "배송준비중"
      },
      {
        "orderNo": "20260702-1002",
        "productName": "보물상자 B",
        "status": "배송완료"
      }
    ]
  }
}

4) Failure response

JSON

{
  "schema": "sidetalk.api-result.v1",
  "success": false,
  "summary": "예약 정보를 찾을 수 없습니다.",
  "error": {
    "code": "NOT_FOUND",
    "message": "일치하는 예약 정보가 없습니다.",
    "detail": "reservationNo 값에 해당하는 데이터가 존재하지 않습니다."
  },
  "meta": {
    "source": "public_api",
    "statusCode": 404
  }
}

Summary

The goal is to give external server responses a common structure that AI can understand easily.

The required basic structure is:

Success: schema, success, data
Failure: schema, success, errors

summary is optional, but recommended because it helps the chatbot understand responses faster and answer more naturally.

The structure inside data is not fixed; design it freely for the API’s purpose.

Use a simple, clear structure that the chatbot can apply directly to answers.