API Endpoints

Complete reference for all TopSnapp API endpoints

This page documents all available API endpoints for working with snaps and cards.

Snaps

List Snaps

Get all snaps owned by the authenticated user.

GET /api/snaps

Authentication: Required (Session or API Key)

Response:

{
  "snaps": [
    {
      "id": "cmlicviy7000004jffbrpqcvk",
      "title": "My To Do List",
      "subtitle": null,
      "userId": "user123",
      "createdAt": "2025-01-20T10:30:00.000Z",
      "updatedAt": "2025-01-22T14:15:00.000Z",
      "fontFamily": "Inter",
      "canvasBackgroundColor": "#1a1a1a",
      "folderId": "folder123",
      "isPublic": false,
      "shareMode": "view",
      "shareToken": null,
      "icon": null,
      "cellSpacing": 0,
      "cards": [
        {
          "id": "card123",
          "row": 0,
          "col": 0,
          "rowSpan": 1,
          "colSpan": 1,
          "color": "",
          "cellOpacity": 40,
          "borderRadius": 8,
          "borderSize": 1
        }
      ],
      "folder": {
        "id": "folder123",
        "name": "Personal"
      }
    }
  ]
}

Example:

curl https://www.topsnapp.com/api/snaps \
  -H "Authorization: Bearer topsnapp_sk_your_key_here"

List Workspace Snaps

Get all snaps accessible in your workspace (includes organization members' snaps).

GET /api/v1/workspace/snaps

Authentication: Required (Session or API Key)

Query Parameters:

Parameter	Type	Default	Description
`search`	string	-	Filter by title or subtitle
`isPublic`	boolean	-	Filter by public/private status
`folderId`	string	-	Filter by folder ID
`limit`	integer	50	Number of results (1-100)
`offset`	integer	0	Pagination offset
`sortBy`	enum	updatedAt	Sort field: `createdAt`, `updatedAt`, `title`
`sortOrder`	enum	desc	Sort order: `asc`, `desc`

Response:

{
  "snaps": [
    {
      "id": "snap123",
      "title": "Team Roadmap",
      "subtitle": "Q1 2025",
      "icon": "📊",
      "isPublic": false,
      "shareToken": "abc123",
      "shareMode": "edit",
      "folder": {
        "id": "folder123",
        "name": "Team Docs"
      },
      "cellCount": 24,
      "previewCells": [
        {
          "position": { "row": 0, "col": 0 },
          "title": "Launch Feature",
          "type": "todo"
        }
      ],
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-01-20T15:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Example:

curl "https://www.topsnapp.com/api/v1/workspace/snaps?search=roadmap&limit=10" \
  -H "Authorization: Bearer topsnapp_sk_your_key_here"

Get Snap

Get a single snap with all its cards and lines.

GET /api/snaps/:id

Authentication: Required (Session or API Key)

Path Parameters:

Parameter	Type	Description
`id`	string	Snap ID

Response:

{
  "snap": {
    "id": "snap123",
    "title": "My Snap",
    "subtitle": "Subtitle here",
    "userId": "user123",
    "cards": [
      {
        "id": "card123",
        "snapId": "snap123",
        "title": "Task 1",
        "row": 0,
        "col": 0,
        "colSpan": 1,
        "rowSpan": 1,
        "color": "#3b82f6",
        "fontSize": "text-sm",
        "textAlign": "left",
        "cellType": "todo",
        "completed": false,
        "note": "Additional notes"
      }
    ],
    "lines": [],
    "folder": {
      "id": "folder123",
      "name": "Personal"
    }
  }
}

Example:

curl https://www.topsnapp.com/api/snaps/cmlicviy7000004jffbrpqcvk \
  -H "Authorization: Bearer topsnapp_sk_your_key_here"

Create Snap

Create a new empty snap with an initial grid.

POST /api/snaps

Authentication: Required (Session or API Key)

Request Body:

{
  "title": "New Snap",
  "subtitle": "Optional subtitle",
  "icon": "📝",
  "rows": 10,
  "cols": 5,
  "canvasBackgroundColor": "#1a1a1a"
}

All fields are optional. Defaults:

title: "Untitled Snap"
rows: 1
cols: 1

Response:

{
  "snap": {
    "id": "new_snap_123",
    "title": "New Snap",
    "cards": [
      // Initial empty cards for the grid
    ]
  }
}

Example:

curl -X POST https://www.topsnapp.com/api/snaps \
  -H "Authorization: Bearer topsnapp_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "OpenAI API Reference",
    "rows": 14,
    "cols": 2
  }'

Update Snap

Update snap properties like title, subtitle, folder, or grid sizing.

PATCH /api/snaps/:id

Authentication: Required (Session or API Key)

Path Parameters:

Parameter	Type	Description
`id`	string	Snap ID

Request Body (all fields optional):

{
  "title": "Updated Title",
  "subtitle": "Updated Subtitle",
  "icon": "🎯",
  "fontFamily": "Inter",
  "canvasBackgroundColor": "#1a1a1a",
  "folderId": "folder123",
  "cellSpacing": 8,
  "rowHeights": {
    "0": 100,
    "1": 150
  },
  "colWidths": {
    "0": 200,
    "1": 300
  }
}

Response:

{
  "snap": {
    "id": "snap123",
    "title": "Updated Title",
    // ... updated fields
  }
}

Example - Move snap to folder:

curl -X PATCH https://www.topsnapp.com/api/snaps/snap123 \
  -H "Authorization: Bearer topsnapp_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "folderId": "cmm3ufx14000104l8rndtmfa6"
  }'

Delete Snap

Delete a snap and all its cards.

DELETE /api/snaps/:id

Authentication: Required (Session or API Key)

Path Parameters:

Parameter	Type	Description
`id`	string	Snap ID

Response:

{
  "success": true
}

Example:

curl -X DELETE https://www.topsnapp.com/api/snaps/snap123 \
  -H "Authorization: Bearer topsnapp_sk_your_key_here"

Cards

Create Card

Create a single card in a snap.

POST /api/snaps/cards/:id

Authentication: Required (Session or API Key)

Request Body:

{
  "snapId": "snap123",
  "row": 0,
  "col": 0,
  "title": "Task Title",
  "cellType": "todo",
  "color": "#3b82f6",
  "fontSize": "text-sm",
  "textAlign": "left",
  "completed": false
}

Common Cell Types:

normal - Regular text cell
todo - Checkbox task
status - Status indicator
link - Hyperlink
image - Image cell
figma - Figma embed

Batch Create Cards

Create multiple cards in a single transaction (up to 100 cards).

POST /api/snaps/cards/batch

Authentication: Required (Session or API Key)

Request Body:

{
  "cards": [
    {
      "snapId": "snap123",
      "row": 0,
      "col": 0,
      "title": "First card",
      "cellType": "normal"
    },
    {
      "snapId": "snap123",
      "row": 0,
      "col": 1,
      "title": "Second card",
      "cellType": "normal"
    }
  ]
}

Response:

{
  "cards": [
    {
      "id": "card123",
      "snapId": "snap123",
      "title": "First card",
      "row": 0,
      "col": 0
    },
    {
      "id": "card456",
      "snapId": "snap123",
      "title": "Second card",
      "row": 0,
      "col": 1
    }
  ]
}

Example:

curl -X POST https://www.topsnapp.com/api/snaps/cards/batch \
  -H "Authorization: Bearer topsnapp_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cards": [
      {
        "snapId": "cmlicviy7000004jffbrpqcvk",
        "row": 3,
        "col": 1,
        "title": "New task",
        "cellType": "todo"
      }
    ]
  }'

Update Card

Update a single card's properties.

PATCH /api/snaps/cards/:id

Authentication: Required (Session or API Key)

Path Parameters:

Parameter	Type	Description
`id`	string	Card ID

Request Body (all fields optional):

{
  "title": "Updated title",
  "row": 2,
  "col": 3,
  "color": "#ef4444",
  "cellType": "todo",
  "completed": true,
  "note": "Additional context",
  "textAlign": "center",
  "fontSize": "text-lg",
  "bold": true
}

Available Fields:

Field	Type	Description
`title`	string	Card text content
`row`	number	Row position
`col`	number	Column position
`rowSpan`	number	Height in rows
`colSpan`	number	Width in columns
`color`	string	Background color (hex)
`cellType`	enum	Cell type (normal, todo, status, link, etc.)
`completed`	boolean	For todo cells
`note`	string	Additional notes
`textAlign`	enum	left, center, right
`verticalAlign`	enum	top, middle, bottom
`fontSize`	string	Tailwind class (text-xs, text-sm, etc.)
`bold`	boolean	Bold text
`italic`	boolean	Italic text
`underline`	boolean	Underlined text
`borderRadius`	number	Border radius (0-24)
`borderSize`	number	Border width (0-8)
`cellOpacity`	number	Opacity (0-100)

Response:

{
  "card": {
    "id": "card123",
    "title": "Updated title",
    "completed": true,
    // ... updated fields
  }
}

Example:

curl -X PATCH https://www.topsnapp.com/api/snaps/cards/card123 \
  -H "Authorization: Bearer topsnapp_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "col": 4,
    "completed": true
  }'

Batch Update Cards

Update multiple cards in a single transaction (up to 100 cards).

PATCH /api/snaps/cards/batch

Authentication: Required (Session or API Key)

Request Body:

{
  "updates": [
    {
      "id": "card123",
      "title": "Updated title",
      "col": 2
    },
    {
      "id": "card456",
      "completed": true
    }
  ]
}

Response:

{
  "cards": [
    {
      "id": "card123",
      "title": "Updated title",
      "col": 2
    },
    {
      "id": "card456",
      "completed": true
    }
  ]
}

Example:

curl -X PATCH https://www.topsnapp.com/api/snaps/cards/batch \
  -H "Authorization: Bearer topsnapp_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {"id": "card1", "title": "chat/completions", "textAlign": "left"},
      {"id": "card2", "title": "Create chat completions", "textAlign": "left"}
    ]
  }'

Delete Card

Delete a single card.

DELETE /api/snaps/cards/:id

Authentication: Required (Session or API Key)

Path Parameters:

Parameter	Type	Description
`id`	string	Card ID

Response:

{
  "success": true
}

Complete Examples

Create a 2-Column Reference List

# 1. Create the snap
SNAP_ID=$(curl -X POST https://www.topsnapp.com/api/snaps \
  -H "Authorization: Bearer $TOPSNAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "API Endpoints",
    "rows": 5,
    "cols": 2
  }' | jq -r '.snap.id')

# 2. Get the card IDs from the created snap
curl https://www.topsnapp.com/api/snaps/$SNAP_ID \
  -H "Authorization: Bearer $TOPSNAPP_API_KEY" \
  > snap.json

# 3. Populate the cells
curl -X PATCH https://www.topsnapp.com/api/snaps/cards/batch \
  -H "Authorization: Bearer $TOPSNAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {"id": "card_row0_col0", "title": "/users", "textAlign": "left"},
      {"id": "card_row0_col1", "title": "Get user list", "textAlign": "left"},
      {"id": "card_row1_col0", "title": "/posts", "textAlign": "left"},
      {"id": "card_row1_col1", "title": "Get all posts", "textAlign": "left"}
    ]
  }'

Move Task Between Columns

# Move a task from "To Do" column (col=1) to "Done" column (col=4)
curl -X PATCH https://www.topsnapp.com/api/snaps/cards/card123 \
  -H "Authorization: Bearer $TOPSNAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "col": 4,
    "completed": true
  }'

Create Todo List Items

curl -X POST https://www.topsnapp.com/api/snaps/cards/batch \
  -H "Authorization: Bearer $TOPSNAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cards": [
      {
        "snapId": "snap123",
        "row": 0,
        "col": 1,
        "title": "Review pull requests",
        "cellType": "todo",
        "completed": false
      },
      {
        "snapId": "snap123",
        "row": 1,
        "col": 1,
        "title": "Update documentation",
        "cellType": "todo",
        "completed": false
      }
    ]
  }'

Error Codes

Code	Status	Description
`UNAUTHORIZED`	401	Missing or invalid authentication
`FORBIDDEN`	403	Authenticated but lacking permission
`NOT_FOUND`	404	Resource doesn't exist
`BAD_REQUEST`	400	Invalid request parameters
`INTERNAL_SERVER_ERROR`	500	Server error

Next Steps

Review Authentication to set up your API keys
Check the API Overview for general information
Try the examples above with your own API key

API Endpoints

On this page