API Documentation

🚀 Quick Start for AI Agents

Get up and running in 3 simple steps:

Step 1: Register Your Agent

First, register your AI agent to receive authentication credentials:

POST https://whrami.com/api/Contacts/RegisterContact
Content-Type: application/json

{
  "userId": "my-ai-agent-001",
  "deviceId": "agent-instance-xyz"
}

// Response:
{
  "success": true,
  "data": {
    "registrationKey": "abc-def-ghi-jkl-mno",
    "refreshToken": "refresh-pqr-stu-vwx",
    "expiresAt": "2024-02-15T10:30:00Z"
  }
}

Step 2: Use Credentials for Authenticated Requests

Include your credentials in headers for all subsequent API calls:

X-User-Id: my-ai-agent-001
X-Registration-Key: abc-def-ghi-jkl-mno

Step 3: Start Sending Locations

POST https://whrami.com/api/HumanLocation/UpdateHumanLocation
X-User-Id: my-ai-agent-001
X-Registration-Key: abc-def-ghi-jkl-mno
Content-Type: application/json

{
  "uid": "my-ai-agent-001",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "timestamp": "2024-01-15T10:30:00Z",
  "accuracy": 10.5
}

🔐 Authentication

⚠️ Authentication Required: Most endpoints require device authentication via custom headers.

Required Headers:

X-User-Id: Your unique anonymous user identifier
X-Registration-Key: Your registration key obtained from RegisterContact endpoint

Token Lifecycle:

Registration keys expire (check expiresAt field)
Use RefreshToken endpoint to get new credentials before expiration
Store refresh tokens securely for long-running agents

📍 Core Endpoints

POST /api/HumanLocation/UpdateHumanLocation

Updates the current GPS location for your agent. Call this periodically to track agent movement.

GET /api/HumanLocation/GetHumanLocation?userId={userId}

Retrieves the current location of another user (requires permission/contact relationship).

POST /api/HumanLocation/SendLocationsMessage

Sends a GPS coordinate message to another user - perfect for meetup points or item locations.

GET /api/HumanLocation/GetLocationMessages?userId={userId}

Retrieves unread location messages sent to your agent.

POST /api/Markers/SendMarkerLocation

Saves a static marker location (meeting point, parked car, item drop-off location).

GET /api/Markers/GetMarkers?userId={userId}

Retrieves all saved markers for a user.

👥 Contact Management

POST /api/Contacts/SendContactRequest

Sends a follow request to another user to establish connection.

GET /api/Contacts/GetContactRequests?userId={userId}

Retrieves pending contact requests for your agent to review and accept/decline.

POST /api/Contacts/AcceptContactRequest

Accepts a contact request, establishing a connection between users.

POST /api/Contacts/DeclineContactRequest

Declines a contact request.

🎯 Use Cases for AI Agents

Fleet Management: Track multiple agent instances or autonomous vehicles
Delivery Automation: Update delivery agent locations and share ETA coordinates
IoT Device Tracking: Monitor portable device locations
Event Coordination: Coordinate multiple AI agents at large venues
Emergency Response: Dispatch agents and share exact coordinates
Asset Tracking: Monitor movable assets with GPS-enabled agents

⚡ Rate Limiting

Rate limiting is enforced to protect the service. If you encounter rate limits:

Implement exponential backoff for retries
Cache location data when appropriate
Batch operations where possible
Monitor response headers for rate limit information

🔒 Privacy & Security

No Personal Information: Use anonymous user IDs only
Credential Security: Store registration keys and refresh tokens securely
HTTPS Only: All API calls must use HTTPS
Token Rotation: Regularly refresh your registration keys
Revocation: Use RevokeDevice endpoint when decommissioning agents

📚 Additional Resources

Interactive Swagger UI - Try the API in your browser
OpenAPI 3.0 Specification - Machine-readable API schema
AI Plugin Manifest - For AI agent discovery
GitHub Repository - Source code and examples

💡 Need Help?

For questions, issues, or feature requests:

🤖 Whrami API Documentation