Authentication

All API requests require a valid API key passed as a Bearer token in the Authorization header. API keys are created by Customer Admins in Settings.

Authorization: Bearer asamano_live_...

Create and manage API keys in Settings → API.

Base URL

https://api.asamano.com

All API endpoints are relative to this base URL.

Endpoints

curl "https://api.asamano.com/api/v1/boxes?limit=20" \
  -H "Authorization: Bearer asamano_live_..."

{
  "data": [
    {
      "id": "box_123",
      "title": "Winter Clothes",
      "description": "Jackets and gloves",
      "qr_code": "QR-ABC-123",
      "location": {
        "building": "Home",
        "room": "Storage",
        "shelf": "Top shelf"
      },
      "tags": ["winter", "clothes"],
      "image_count": 3,
      "item_count": 12,
      "category": "clothing",
      "owner": "John Doe",
      "created_at": "2026-04-01T10:00:00Z",
      "updated_at": "2026-04-05T12:00:00Z"
    }
  ],
  "next_cursor": "cursor_abc123"
}

Pagination

The API uses cursor-based pagination. Each response includes a next_cursor field. Pass it as the cursor parameter in your next request to fetch the next page.

1. Make a request with an optional limit parameter
2. Check the next_cursor field in the response
3. Pass next_cursor as the cursor parameter in your next request

// Fetch all boxes using cursor pagination
let cursor = null;
let allBoxes = [];

do {
  const url = new URL("https://api.asamano.com/api/v1/boxes");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const res = await fetch(url, {
    headers: { Authorization: "Bearer asamano_live_..." }
  });
  const json = await res.json();

  allBoxes = allBoxes.concat(json.data);
  cursor = json.next_cursor;
} while (cursor);

Rate Limiting

API requests are rate-limited per calendar month based on your subscription plan.

Error Handling

The API returns consistent error responses with a machine-readable error code and a human-readable message.

{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded your monthly API request limit"
}

Code Examples

curl "https://api.asamano.com/api/v1/boxes?limit=20" \
  -H "Authorization: Bearer asamano_live_..."

OpenAPI Specification

Download the OpenAPI 3.0 specification to import into Postman, Insomnia, or your favorite API tool.