Content is user-generated and unverified.

User Data Management API Documentation

Base URL

https://api.yourservice.com/v1

Authentication

All requests require authentication via Bearer token in the Authorization header:

Authorization: Bearer <your-token>

1. Conversation History Endpoints

1.1 Get Conversation History

Retrieve conversation history summary for a specific user.

Endpoint: GET /conversations/{user_id}

Path Parameters:

  • user_id (string, required): Unique identifier for the user

Query Parameters:

  • date (string, optional): Date in ISO 8601 format (YYYY-MM-DD)
  • time (string, optional): Time in ISO 8601 format (HH:MM:SS)

Request Example:

http
GET /conversations/user123?date=2025-07-02&time=14:30:00
Authorization: Bearer your-token-here

Response Schema:

json
{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "string",
      "description": "Unique identifier for the user"
    },
    "conversation_summary": {
      "type": "string",
      "description": "Paragraph summary of conversation history"
    },
    "last_updated": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp of last conversation update"
    },
    "total_conversations": {
      "type": "integer",
      "description": "Total number of conversations"
    }
  },
  "required": ["user_id", "conversation_summary", "last_updated"]
}

Response Example:

json
{
  "user_id": "user123",
  "conversation_summary": "User has been discussing productivity techniques and time management strategies. Recent conversations focused on implementing GTD methodology and exploring digital tools for task organization. User expressed interest in meditation and mindfulness practices.",
  "last_updated": "2025-07-02T14:30:00Z",
  "total_conversations": 15
}

1.2 Create/Update Conversation History

Push conversation history summary for a specific user.

Endpoint: POST /conversations

Request Schema:

json
{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "string",
      "description": "Unique identifier for the user"
    },
    "conversation_id": {
      "type": "string",
      "description": "Unique identifier for the conversation"
    },
    "conversation_summary": {
      "type": "string",
      "description": "Paragraph summary of the conversation",
      "maxLength": 2000
    },
    "date": {
      "type": "string",
      "format": "date",
      "description": "Date of conversation (YYYY-MM-DD)"
    },
    "time": {
      "type": "string",
      "pattern": "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$",
      "description": "Time of conversation (HH:MM:SS)"
    },
    "location": {
      "type": "object",
      "properties": {
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        "address": {
          "type": "string",
          "description": "Human-readable address"
        }
      }
    }
  },
  "required": ["user_id", "conversation_id", "conversation_summary", "date", "time"]
}

Request Example:

json
{
  "user_id": "user123",
  "conversation_id": "conv456",
  "conversation_summary": "User discussed implementing a new morning routine including meditation, exercise, and journaling. Expressed concerns about maintaining consistency and requested strategies for habit formation.",
  "date": "2025-07-02",
  "time": "14:30:00",
  "location": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "address": "New York, NY, USA"
  }
}

Response Schema:

json
{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "message": {
      "type": "string"
    },
    "conversation_id": {
      "type": "string"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": ["success", "message"]
}

2. User Data Endpoints

2.1 Get User Data

Retrieve user traits and sentiments for a specific user.

Endpoint: GET /users/{user_id}/data

Path Parameters:

  • user_id (string, required): Unique identifier for the user

Query Parameters:

  • date (string, optional): Date in ISO 8601 format (YYYY-MM-DD)
  • time (string, optional): Time in ISO 8601 format (HH:MM:SS)

Request Example:

http
GET /users/user123/data?date=2025-07-02&time=14:30:00
Authorization: Bearer your-token-here

Response Schema:

json
{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "string",
      "description": "Unique identifier for the user"
    },
    "user_traits": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "trait_name": {
            "type": "string",
            "enum": ["openness", "conscientiousness", "extraversion", "agreeableness", "neuroticism", "optimism", "creativity", "leadership"]
          },
          "score": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Trait score between 0 and 1"
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Confidence level of the assessment"
          }
        },
        "required": ["trait_name", "score"]
      }
    },
    "sentiments": {
      "type": "object",
      "properties": {
        "overall_sentiment": {
          "type": "string",
          "enum": ["positive", "negative", "neutral"]
        },
        "sentiment_score": {
          "type": "number",
          "minimum": -1,
          "maximum": 1,
          "description": "Sentiment score from -1 (very negative) to 1 (very positive)"
        },
        "emotions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "emotion": {
                "type": "string",
                "enum": ["joy", "sadness", "anger", "fear", "surprise", "disgust", "trust", "anticipation"]
              },
              "intensity": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              }
            }
          }
        }
      }
    },
    "last_updated": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": ["user_id", "user_traits", "sentiments", "last_updated"]
}

Response Example:

json
{
  "user_id": "user123",
  "user_traits": [
    {
      "trait_name": "openness",
      "score": 0.85,
      "confidence": 0.92
    },
    {
      "trait_name": "conscientiousness",
      "score": 0.78,
      "confidence": 0.88
    }
  ],
  "sentiments": {
    "overall_sentiment": "positive",
    "sentiment_score": 0.65,
    "emotions": [
      {
        "emotion": "joy",
        "intensity": 0.7
      },
      {
        "emotion": "anticipation",
        "intensity": 0.5
      }
    ]
  },
  "last_updated": "2025-07-02T14:30:00Z"
}

2.2 Update User Data

Push identified traits and sentiments for a user.

Endpoint: POST /users/data

Request Schema:

json
{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "string",
      "description": "Unique identifier for the user"
    },
    "user_traits": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "trait_name": {
            "type": "string",
            "enum": ["openness", "conscientiousness", "extraversion", "agreeableness", "neuroticism", "optimism", "creativity", "leadership"]
          },
          "score": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          }
        },
        "required": ["trait_name", "score"]
      }
    },
    "sentiments": {
      "type": "object",
      "properties": {
        "overall_sentiment": {
          "type": "string",
          "enum": ["positive", "negative", "neutral"]
        },
        "sentiment_score": {
          "type": "number",
          "minimum": -1,
          "maximum": 1
        },
        "emotions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "emotion": {
                "type": "string",
                "enum": ["joy", "sadness", "anger", "fear", "surprise", "disgust", "trust", "anticipation"]
              },
              "intensity": {
                "type": "number",
                "minimum": 0,
                "maximum": 1
              }
            }
          }
        }
      }
    },
    "date": {
      "type": "string",
      "format": "date"
    },
    "time": {
      "type": "string",
      "pattern": "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$"
    },
    "location": {
      "type": "object",
      "properties": {
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        "address": {
          "type": "string"
        }
      }
    }
  },
  "required": ["user_id", "user_traits", "sentiments", "date", "time"]
}

Request Example:

json
{
  "user_id": "user123",
  "user_traits": [
    {
      "trait_name": "openness",
      "score": 0.85,
      "confidence": 0.92
    },
    {
      "trait_name": "conscientiousness",
      "score": 0.78,
      "confidence": 0.88
    }
  ],
  "sentiments": {
    "overall_sentiment": "positive",
    "sentiment_score": 0.65,
    "emotions": [
      {
        "emotion": "joy",
        "intensity": 0.7
      }
    ]
  },
  "date": "2025-07-02",
  "time": "14:30:00",
  "location": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "address": "New York, NY, USA"
  }
}

3. Activity Data Endpoints

3.1 Get Activity Data

Retrieve top 5 recent activity details for a user.

Endpoint: GET /users/{user_id}/activities

Path Parameters:

  • user_id (string, required): Unique identifier for the user

Query Parameters:

  • limit (integer, optional, default: 5): Number of activities to return (max 10)

Request Example:

http
GET /users/user123/activities?limit=5
Authorization: Bearer your-token-here

Response Schema:

json
{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "string"
    },
    "activities": {
      "type": "array",
      "maxItems": 10,
      "items": {
        "type": "object",
        "properties": {
          "activity_id": {
            "type": "string"
          },
          "activity_name": {
            "type": "string",
            "description": "Name or description of the activity"
          },
          "activity_type": {
            "type": "string",
            "enum": ["exercise", "work", "social", "leisure", "travel", "education", "health", "other"]
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "time": {
            "type": "string",
            "pattern": "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$"
          },
          "location": {
            "type": "object",
            "properties": {
              "latitude": {
                "type": "number",
                "minimum": -90,
                "maximum": 90
              },
              "longitude": {
                "type": "number",
                "minimum": -180,
                "maximum": 180
              },
              "address": {
                "type": "string"
              }
            }
          },
          "weather": {
            "type": "object",
            "properties": {
              "temperature": {
                "type": "number",
                "description": "Temperature in Celsius"
              },
              "humidity": {
                "type": "number",
                "minimum": 0,
                "maximum": 100,
                "description": "Humidity percentage"
              },
              "condition": {
                "type": "string",
                "enum": ["sunny", "cloudy", "rainy", "snowy", "windy", "foggy", "stormy"]
              },
              "description": {
                "type": "string",
                "description": "Detailed weather description"
              }
            }
          },
          "duration_minutes": {
            "type": "integer",
            "minimum": 0,
            "description": "Duration of activity in minutes"
          }
        },
        "required": ["activity_id", "activity_name", "date", "time", "location", "weather"]
      }
    },
    "total_activities": {
      "type": "integer"
    }
  },
  "required": ["user_id", "activities"]
}

Response Example:

json
{
  "user_id": "user123",
  "activities": [
    {
      "activity_id": "act789",
      "activity_name": "Morning Jog in Central Park",
      "activity_type": "exercise",
      "date": "2025-07-02",
      "time": "07:00:00",
      "location": {
        "latitude": 40.7829,
        "longitude": -73.9654,
        "address": "Central Park, New York, NY"
      },
      "weather": {
        "temperature": 22,
        "humidity": 65,
        "condition": "sunny",
        "description": "Clear sky with light breeze"
      },
      "duration_minutes": 45
    }
  ],
  "total_activities": 25
}

3.2 Create Activity Data

Push new activity data for a user.

Endpoint: POST /users/activities

Request Schema:

json
{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "string",
      "description": "Unique identifier for the user"
    },
    "activity_name": {
      "type": "string",
      "description": "Name or description of the activity"
    },
    "activity_type": {
      "type": "string",
      "enum": ["exercise", "work", "social", "leisure", "travel", "education", "health", "other"]
    },
    "date": {
      "type": "string",
      "format": "date"
    },
    "time": {
      "type": "string",
      "pattern": "^([0-1]?[0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$"
    },
    "location": {
      "type": "object",
      "properties": {
        "latitude": {
          "type": "number",
          "minimum": -90,
          "maximum": 90
        },
        "longitude": {
          "type": "number",
          "minimum": -180,
          "maximum": 180
        },
        "address": {
          "type": "string"
        }
      },
      "required": ["latitude", "longitude"]
    },
    "weather": {
      "type": "object",
      "properties": {
        "temperature": {
          "type": "number"
        },
        "humidity": {
          "type": "number",
          "minimum": 0,
          "maximum": 100
        },
        "condition": {
          "type": "string",
          "enum": ["sunny", "cloudy", "rainy", "snowy", "windy", "foggy", "stormy"]
        },
        "description": {
          "type": "string"
        }
      },
      "required": ["temperature", "condition"]
    },
    "duration_minutes": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": ["user_id", "activity_name", "date", "time", "location", "weather"]
}

Request Example:

json
{
  "user_id": "user123",
  "activity_name": "Yoga Session at Home",
  "activity_type": "exercise",
  "date": "2025-07-02",
  "time": "18:30:00",
  "location": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "address": "Home, New York, NY"
  },
  "weather": {
    "temperature": 24,
    "humidity": 70,
    "condition": "cloudy",
    "description": "Overcast with mild temperature"
  },
  "duration_minutes": 60
}

Response Schema:

json
{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "message": {
      "type": "string"
    },
    "activity_id": {
      "type": "string"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  },
  "required": ["success", "message"]
}

Error Responses

All endpoints may return the following error responses:

400 Bad Request

json
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "user_id",
        "message": "User ID is required"
      }
    ]
  }
}

401 Unauthorized

json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired authentication token"
  }
}

404 Not Found

json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "User not found"
  }
}

500 Internal Server Error

json
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}

Rate Limits

  • GET requests: 100 requests per minute per user
  • POST requests: 50 requests per minute per user

Rate limit headers are included in all responses:

  • X-RateLimit-Limit: Request limit per minute
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Unix timestamp when the rate limit resets

Data Types Reference

Date Format

All dates should follow ISO 8601 format: YYYY-MM-DD (e.g., "2025-07-02")

Time Format

All times should follow 24-hour format: HH:MM:SS (e.g., "14:30:00")

Location Object

Coordinates should use WGS84 datum:

  • Latitude: -90 to 90 (negative for South)
  • Longitude: -180 to 180 (negative for West)

Trait Scores

All psychological trait scores are normalized between 0 and 1, where:

  • 0 = Very low expression of the trait
  • 0.5 = Average expression of the trait
  • 1 = Very high expression of the trait

Sentiment Scores

Sentiment scores range from -1 to 1, where:

  • -1 = Very negative sentiment
  • 0 = Neutral sentiment
  • 1 = Very positive sentiment
Content is user-generated and unverified.
    User Data Management API Documentation | Claude