Protocol Specification

All Data Contract endpoints accept POST requests with a JSON body and return JSON responses. Requests are authenticated via HMAC signatures.

Common Request Headers

Header	Description
`Content-Type`	`application/json`
`X-Signature`	HMAC-SHA256 signature
`X-Timestamp`	Unix timestamp (ms) of the request
`X-Request-Id`	Unique request identifier

Common Request Body

All endpoints receive:

{
  "userId": "usr_abc123",
  "action": "describe" | "export" | "delete"
}

`describe`

Returns a description of what data the app stores for a given user.

Request:

{
  "userId": "usr_abc123",
  "action": "describe"
}

Response (200):

{
  "status": "ok",
  "data": {
    "fields": [
      {
        "name": "profile",
        "description": "User profile information",
        "fields": [
          { "name": "displayName", "type": "string", "description": "Display name" },
          { "name": "email", "type": "string", "description": "Email address" },
          { "name": "avatarUrl", "type": "string", "description": "Profile picture URL" }
        ]
      },
      {
        "name": "preferences",
        "description": "App preferences and settings",
        "fields": [
          { "name": "theme", "type": "string", "description": "UI theme preference" },
          { "name": "notifications", "type": "boolean", "description": "Notification opt-in" }
        ]
      }
    ]
  }
}

`export`

Returns all data stored for the user.

Request:

{
  "userId": "usr_abc123",
  "action": "export"
}

Response (200):

{
  "status": "ok",
  "data": {
    "profile": {
      "displayName": "Alice",
      "email": "alice@example.com",
      "avatarUrl": "https://cdn.example.com/alice.jpg"
    },
    "preferences": {
      "theme": "dark",
      "notifications": true
    },
    "activity": [
      { "type": "login", "timestamp": "2025-01-15T10:30:00Z" }
    ]
  }
}

`delete`

Deletes all data for the user. Supports both synchronous and asynchronous deletion.

Request:

{
  "userId": "usr_abc123",
  "action": "delete"
}

Synchronous Response (200):

{
  "status": "completed"
}

Asynchronous Response (202):

{
  "status": "pending",
  "trackingId": "del_xyz789",
  "estimatedCompletionMs": 30000
}

Polling Async Deletions

When a deletion returns status: "pending", the platform polls the same endpoint with the tracking ID:

{
  "userId": "usr_abc123",
  "action": "delete",
  "trackingId": "del_xyz789"
}

Poll Response — Still Processing (202):

{
  "status": "pending",
  "trackingId": "del_xyz789"
}

Poll Response — Complete (200):

{
  "status": "completed",
  "trackingId": "del_xyz789"
}

Status Codes

Code	Meaning
`200`	Success — operation completed
`202`	Accepted — async deletion in progress
`400`	Bad request — invalid payload
`401`	Unauthorized — invalid or missing signature
`404`	User not found
`429`	Rate limited
`500`	Internal server error

Error Response

{
  "status": "error",
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "No data found for the specified user"
  }
}

Error codes: INVALID_ACTION, USER_NOT_FOUND, INVALID_SIGNATURE, RATE_LIMITED, INTERNAL_ERROR.

Overview Implementation Guide