Home/Guides/Response Format

Response Format

Standard envelope structure for API responses.

Overview

The BlueAI API uses a consistent response format across all endpoints. Standard envelopes are defined for single objects, lists, and errors, enabling uniform handling on the client side. All field names are returned in snake_case.

Single Object Response

Endpoints that return a single resource (e.g. GET /resource/:id, POST /resource) return the resource object directly. Each object includes id and object fields.

{
  "id": "deal_11111111111111111111111111111111",
  "object": "deal",
  "name": "Enterprise Contract",
  "amount": 1500000,
  "status": "open",
  "created_at": "2025-01-15T09:00:00Z",
  "updated_at": "2025-02-10T14:30:00Z"
}

Field	Type	Description
id	string	Unique identifier for the resource. Prefixed (e.g. deal_xxxx, inv_xxxx).
object	string	A string indicating the resource type (e.g. "deal", "invoice").
created_at	string	When the resource was created (ISO 8601 format).
updated_at	string	When the resource was last updated (ISO 8601 format).

List Response

List endpoints return a standard envelope containing a data array and pagination information.

{
  "object": "list",
  "data": [
    {
      "id": "deal_11111111111111111111111111111111",
      "object": "deal",
      "name": "Enterprise Contract",
      "amount": 1500000,
      "status": "open"
    },
    {
      "id": "deal_22222222222222222222222222222222",
      "object": "deal",
      "name": "Starter Plan",
      "amount": 300000,
      "status": "won"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 142,
    "total_pages": 3
  }
}

Field	Type	Description
object	string	Always set to "list".
data	array	An array of resource objects.
pagination	object	An object containing pagination metadata (page, per_page, total, total_pages).

Error Response

When an error occurs, a response containing an error object is returned. All errors follow a consistent structure.

{
  "error": {
    "type": "invalid_request_error",
    "code": "required",
    "message": "name is required",
    "param": "name"
  }
}

422 Unprocessable Entity:

{
  "error": {
    "type": "validation_error",
    "code": "invalid_parameters",
    "message": "One or more parameters are invalid",
    "errors": [
      {
        "field": "email",
        "code": "invalid_format",
        "message": "must be a valid email address"
      },
      {
        "field": "amount",
        "code": "out_of_range",
        "message": "must be greater than 0"
      }
    ]
  }
}

Field	Type	Description
error.type	string	The error classification (e.g. invalid_request_error, authentication_error).
error.code	string	A machine-readable error code (e.g. required, invalid_format).
error.message	string	A human-readable description of the error.
error.param	string \| null	The parameter related to the error (if applicable).
error.errors	array \| null	An array of validation error details (for 422 errors). Each element contains field, code, and message.

HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of a request.

Status	Meaning	Description
200	OK	The request succeeded. The response body contains the resource.
201	Created	The resource was successfully created. The response body contains the created resource.
204	No Content	The request succeeded but there is no content to return (e.g. DELETE operations).
400	Bad Request	The request body or parameters are invalid.
401	Unauthorized	No valid session or API key was provided.
403	Forbidden	Authenticated, but you do not have permission to perform this action.
404	Not Found	The requested resource does not exist.
409	Conflict	The request conflicts with the current state (e.g. duplicate entry).
422	Unprocessable Entity	The request is well-formed but contains semantic errors. The errors array contains per-field details.
429	Too Many Requests	Rate limit exceeded. See the Rate Limiting guide.
500	Internal Server Error	An unexpected error occurred on the server. Please retry after a short wait.

Naming Conventions

All response fields are returned in snake_case. Request bodies should also be sent in snake_case. Do not use camelCase or PascalCase.

Correct (snake_case)

{
  "company_name": "Acme Corp",
  "created_at": "2025-01-15T09:00:00Z",
  "total_amount": 1500000,
  "is_active": true
}

Incorrect (camelCase)

{
  "companyName": "Acme Corp",
  "createdAt": "2025-01-15T09:00:00Z",
  "totalAmount": 1500000,
  "isActive": true
}

Example

# Fetch a single deal
curl https://api.blueai.jp/api/v1/crm/deals/deal_11111111111111111111111111111111 \
  -b cookies.txt

const res = await fetch(
  "https://api.blueai.jp/api/v1/crm/deals",
  { credentials: "include" },
);
const json = await res.json();

if (json.error) {
  // Error envelope
  console.error(json.error.type, json.error.message);
} else if (json.object === "list") {
  // List envelope
  for (const deal of json.data) {
    console.log(deal.id, deal.name);
  }
  console.log(`Total: ${json.pagination.total}`);
} else {
  // Single object
  console.log(json.id, json.name);
}