Request/Response Schemas

Complete reference for all request and response schemas used by the Memory Scope API.

POST /memory - Create Memory

Request Schema

{
  "user_id": "string (required) - Unique user identifier",
  "scope": "string (required) - One of: preferences, constraints, communication, accessibility, schedule, attention",
  "domain": "string (optional) - Sub-category within the scope",
  "source": "string (required) - Source of memory (e.g., 'explicit_user_input', 'inferred', 'system')",
  "ttl_days": "number (optional) - Time-to-live in days (1-365). Default: null (no expiration)",
  "value_json": "object | array (required) - Memory data as JSON"
}

Response Schema

{
  "id": "string (UUID) - Memory ID",
  "user_id": "string - User identifier",
  "scope": "string - Scope category",
  "domain": "string | null - Domain sub-category",
  "created_at": "string (ISO 8601) - Creation timestamp",
  "expires_at": "string (ISO 8601) | null - Expiration timestamp"
}

Example Request

{
  "user_id": "user123",
  "scope": "preferences",
  "domain": "food",
  "source": "explicit_user_input",
  "ttl_days": 30,
  "value_json": {
    "likes": [
      "pizza",
      "sushi"
    ],
    "dislikes": [
      "broccoli"
    ]
  }
}

Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "user123",
  "scope": "preferences",
  "domain": "food",
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2024-02-14T10:30:00Z"
}

View full endpoint documentation →

POST /memory/read - Read Memory

Request Schema

{
  "user_id": "string (required) - Unique user identifier",
  "scope": "string (required) - One of: preferences, constraints, communication, accessibility, schedule, attention",
  "domain": "string (optional) - Filter by domain",
  "purpose": "string (required) - Purpose for accessing memory",
  "max_age_days": "number (optional) - Only return memories created within this many days. Default: null"
}

Response Schema

{
  "summary_text": "string - Human-readable summary",
  "summary_struct": "object - Merged memory data as structured JSON",
  "confidence": "number (0.0-1.0) - Confidence score for merged result",
  "revocation_token": "string (UUID) - Token for revoking access",
  "expires_at": "string (ISO 8601) - Token expiration timestamp"
}

Example Request

{
  "user_id": "user123",
  "scope": "preferences",
  "domain": "food",
  "purpose": "generate food recommendations",
  "max_age_days": 30
}

Example Response

{
  "summary_text": "Likes: 2, Dislikes: 1, Settings: 0",
  "summary_struct": {
    "likes": [
      "pizza",
      "sushi"
    ],
    "dislikes": [
      "broccoli"
    ],
    "settings": {}
  },
  "confidence": 0.85,
  "revocation_token": "550e8400-e29b-41d4-a716-446655440000",
  "expires_at": "2024-01-16T10:30:00Z"
}

View full endpoint documentation →

POST /memory/read/continue - Continue Reading

Request Schema

{
  "revocation_token": "string (required, UUID) - Revocation token from previous read"
}

Response Schema

Same as POST /memory/read response schema.

Response Schema

{
  "summary_text": "string - Human-readable summary",
  "summary_struct": "object - Merged memory data as structured JSON",
  "confidence": "number (0.0-1.0) - Confidence score",
  "revocation_token": "string (UUID) - Same revocation token (reused)",
  "expires_at": "string (ISO 8601) - Token expiration timestamp"
}

Example Request

{
  "revocation_token": "550e8400-e29b-41d4-a716-446655440000"
}

View full endpoint documentation →

POST /memory/revoke - Revoke Access

Request Schema

{
  "revocation_token": "string (required, UUID) - Revocation token to revoke"
}

Response Schema

{
  "revoked": "boolean - Whether revocation was successful",
  "revoked_at": "string (ISO 8601) - Revocation timestamp"
}

Example Request

{
  "revocation_token": "550e8400-e29b-41d4-a716-446655440000"
}

Example Response

{
  "revoked": true,
  "revoked_at": "2024-01-15T12:00:00Z"
}

View full endpoint documentation →

Error Response Schema

Standard Error Response

Error Response Schema

{
  "error": {
    "code": "string - Error code (e.g., 'policy_denied', 'invalid_request')",
    "message": "string - Human-readable error message",
    "details": "object (optional) - Additional error details"
  }
}

Example Error Responses

Policy Denied Error

{
  "error": {
    "code": "policy_denied",
    "message": "Purpose 'execute task' is not allowed for scope 'preferences'",
    "details": {
      "scope": "preferences",
      "purpose": "execute task",
      "allowed_purpose_classes": [
        "content_generation",
        "recommendation"
      ]
    }
  }
}

View complete error reference →

Common Data Types

Scope Values

Allowed Scopes

[
  "preferences",
  "constraints",
  "communication",
  "accessibility",
  "schedule",
  "attention"
]

Source Values

Allowed Sources

[
  "explicit_user_input",
  "inferred",
  "system",
  "conversation",
  "user_feedback"
]

Value JSON Shapes

The value_json field can take different shapes depending on the scope:

Value JSON Shapes

{
  "likes_dislikes": {
    "likes": [
      "string"
    ],
    "dislikes": [
      "string"
    ],
    "settings": {}
  },
  "boolean_flags": {
    "key": "boolean"
  },
  "rules_list": [
    "string"
  ],
  "schedule_windows": [
    {
      "day": "string",
      "start": "string",
      "end": "string"
    }
  ],
  "kv_map": {
    "key": "any"
  }
}