API Reference

ByteBox APIs are Next.js route handlers under src/app/api/*.

Cards Collection

GET /api/cards

• Returns { boardData, cards, tags }.
• Ensures default categories exist when DB is empty.

POST /api/cards

• Creates a card with optional tags.
• Accepts tagNames: string[] (preferred) and legacy tags compatibility input.

PATCH /api/cards

• Bulk reorder/move endpoint.
• Request shape:

{
  "updates": [
    { "id": "card_1", "categoryId": "cat_2", "order": 3 }
  ]
}

DELETE /api/cards

• Destructive maintenance endpoint.
• Deletes all cards, tags, and categories.

Single Card

GET /api/cards/[id]

• Fetches one card by ID.
• Returns 404 if not found.

PUT /api/cards/[id]

• Full update path.
• Returns updated card.

PATCH /api/cards/[id]

• Supports star toggle action:
  • { "action": "toggleStar" }
• Supports partial updates:
  • title, description, content, language, starred, categoryId, tagNames

DELETE /api/cards/[id]

• Deletes one card by ID.
• Returns 404 if not found.

Categories

GET /api/categories

• Returns all categories.

POST /api/categories

• Requires name.
• Optional description.
• Defaults color to #ec4899.

PATCH /api/categories/[id]

• Supports name and color.
• Validates target category exists.

DELETE /api/categories/[id]

• Deletes a category by ID.
• Existing cards cascade via relation.

Tags

GET /api/tags

• Returns tags sorted by name.
• Includes _count.cards for each tag.

POST /api/tags

• Requires non-empty name with max length 32.
• Restricts color to allowed palette values.

DELETE /api/tags/[id]

• Deletes one tag by ID.

Settings

GET /api/settings

• Returns singleton user settings payload.

PATCH /api/settings

• Partial update for appearance/settings state.

PUT /api/settings

• Replace-style update path (same update helper currently).

Data Portability

GET /api/export

• Exports metadata + categories/tags/cards payload.
• Does not currently include rich fields like imageData, fileData, starred.

POST /api/import

• Validates payload shape and app identity (ByteBox).
• Upserts categories, tags, and cards in a transaction.

Health and Response Patterns

• Health check endpoint: GET /api/cards
• Success responses are entity payloads or { success: true }
• Error payload shape: { error: "..." } with HTTP status
• Dynamic route params are awaited in handlers:
  • { params }: { params: Promise<{ id: string }> }