Social Data API

Manage public data collections for pages with Social App storage. Records are publicly readable, but only creators can edit their own.

Records are visible to all users, but only the creator can update or delete their own records. Collection names must be lowercase alphanumeric with underscores (e.g., posts, comments).

Endpoints

GET /api/pages/:id/social-data/:collection

List all records in a collection. Records from all users are returned. Requires social-data:read scope.

Query Parameters

Example

curl -H "Authorization: Bearer vm_your_token_here" \
  "https://visimade.com/api/pages/123/social-data/posts?limit=10"

Response

{
  "records": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "collection": "posts",
      "data": { "title": "Hello World", "content": "This is my first post!" },
      "createdBy": { "id": 42, "username": "johndoe" },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 25, "limit": 10, "offset": 0, "hasMore": true
}

# Get the 20 most recent posts
curl "https://visimade.com/api/pages/123/social-data/posts?limit=20"

# Load older posts (use the smallest ID from previous results)
curl "https://visimade.com/api/pages/123/social-data/posts?limit=20&before=456"

# Poll for new posts since your last fetch
curl "https://visimade.com/api/pages/123/social-data/posts?after=500&order=asc"

GET /api/pages/:id/social-data/:collection/count

Count records in a collection, optionally grouped by a data field. No authentication required for simple counts. Use mine=true with authentication to count only your own records.

Query Parameters

// Count comments on a post
curl "https://visimade.com/api/pages/123/social-data/comments/count?where=%7B%22postId%22%3A%22456%22%7D"
// { "count": 18 }

// Count comments grouped by post
curl "https://visimade.com/api/pages/123/social-data/comments/count?groupBy=postId"
// { "counts": { "456": 18, "789": 5 } }

POST /api/pages/:id/social-data/:collection

Create a new record in a collection. Requires social-data:write scope.

Example

curl -X POST \
  -H "Authorization: Bearer vm_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"data": {"title": "New post", "content": "Hello world!"}}' \
  https://visimade.com/api/pages/123/social-data/posts

PATCH /api/pages/:id/social-data/:collection/:recordId

Update an existing record. You can only update records you created. Requires social-data:write scope.

Example

curl -X PATCH \
  -H "Authorization: Bearer vm_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"data": {"content": "Updated content"}}' \
  https://visimade.com/api/pages/123/social-data/posts/550e8400-e29b-41d4-a716-446655440000

DELETE /api/pages/:id/social-data/:collection/:recordId

Delete a record. You can only delete records you created. Requires social-data:write scope.

curl -X DELETE \
  -H "Authorization: Bearer vm_your_token_here" \
  https://visimade.com/api/pages/123/social-data/posts/550e8400-e29b-41d4-a716-446655440000

Batch Operations

Execute up to 100 create, update, and delete operations in a single request. The entire batch runs in one database transaction (all-or-nothing) and counts as a single rate limit hit. Users can create freely but can only update and delete their own records.

Request Body

{
  "operations": [
    { "op": "create", "data": { "text": "Hello!" } },
    { "op": "update", "id": "uuid-1", "data": { "text": "Updated" } },
    { "op": "delete", "id": "uuid-2" }
  ]
}

Response

{
  "results": [
    { "op": "create", "success": true, "id": "uuid-new", "data": { "text": "Hello!" } },
    { "op": "update", "success": true, "id": "uuid-1" },
    { "op": "delete", "success": true, "id": "uuid-2" }
  ]
}