API Reference

API Reference

Base URL: https://api.aiffinity.me/v1

The Aiffinity API lets you integrate with the platform programmatically. Use it to access AI Soul data, manage contacts, send messages, and trigger agent actions.

Authentication

All API requests require a Bearer token in the Authorization header:

curl -X GET https://api.aiffinity.me/v1/me \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Obtaining a Token

Authenticate using Firebase Auth to receive a JWT token. Include this token in all subsequent API requests.

POST /v1/auth/login
Content-Type: application/json

{
  "firebase_token": "eyJhbGciOiJSUzI1NiIs..."
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2026-03-15T00:00:00Z",
  "user": {
    "id": "usr_abc123",
    "name": "Alex",
    "email": "alex@example.com"
  }
}

Rate Limits

Tier Requests / minute Requests / day
Free 60 1,000
Pro 300 10,000
Enterprise Custom Custom

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Endpoints

GET /v1/me

Returns the authenticated user's profile.

curl https://api.aiffinity.me/v1/me \
  -H "Authorization: Bearer YOUR_TOKEN"
{
  "id": "usr_abc123",
  "name": "Alex",
  "email": "alex@example.com",
  "created_at": "2026-01-15T10:30:00Z",
  "soul_id": "soul_xyz789"
}

GET /v1/soul

Returns the authenticated user's AI Soul data.

curl https://api.aiffinity.me/v1/soul \
  -H "Authorization: Bearer YOUR_TOKEN"
{
  "id": "soul_xyz789",
  "user_id": "usr_abc123",
  "traits": {
    "communication_style": "casual",
    "humour": "dry",
    "formality": 0.3,
    "empathy": 0.8
  },
  "values": ["authenticity", "creativity", "independence"],
  "updated_at": "2026-03-14T12:00:00Z"
}

POST /v1/soul/export

Exports the AI Soul in a portable format for use with third-party services.

curl -X POST https://api.aiffinity.me/v1/soul/export \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"format": "json"}'
{
  "export_url": "https://api.aiffinity.me/v1/exports/exp_abc123",
  "expires_at": "2026-03-15T12:00:00Z",
  "format": "json"
}

GET /v1/contacts

Lists the user's contacts.

curl "https://api.aiffinity.me/v1/contacts?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_TOKEN"
{
  "contacts": [
    {
      "id": "con_def456",
      "name": "Sarah",
      "relationship_score": 0.85,
      "last_interaction": "2026-03-13T18:45:00Z"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

POST /v1/messages

Sends a message to a contact or group.

curl -X POST https://api.aiffinity.me/v1/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_id": "con_def456",
    "content": "Hey, are we still on for dinner tonight?",
    "type": "text"
  }'
{
  "id": "msg_ghi789",
  "status": "sent",
  "created_at": "2026-03-14T14:30:00Z"
}

POST /v1/agents/execute

Triggers an agent action on behalf of the user.

curl -X POST https://api.aiffinity.me/v1/agents/execute \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "draft_email",
    "params": {
      "to": "sarah@example.com",
      "subject": "Follow up on project",
      "context": "We discussed the timeline last week, need to confirm deadlines"
    }
  }'
{
  "id": "act_jkl012",
  "status": "completed",
  "result": {
    "draft": "Hi Sarah,\n\nHope you're doing well! I wanted to follow up on our conversation last week about the project timeline. Could you confirm the deadlines we discussed?\n\nLooking forward to hearing from you.\n\nBest,\nAlex"
  }
}

DELETE /v1/soul

Permanently deletes the user's AI Soul. This action cannot be undone.

curl -X DELETE https://api.aiffinity.me/v1/soul \
  -H "Authorization: Bearer YOUR_TOKEN"
{
  "deleted": true,
  "message": "AI Soul has been permanently deleted."
}

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token.",
    "status": 401
  }
}
Status Code Description
400 BAD_REQUEST Invalid request parameters
401 UNAUTHORIZED Missing or invalid authentication
403 FORBIDDEN Insufficient permissions
404 NOT_FOUND Resource not found
429 RATE_LIMITED Too many requests
500 INTERNAL_ERROR Server error

WebSocket API

For real-time messaging and presence, connect to the WebSocket gateway:

wss://ws.aiffinity.me?token=YOUR_TOKEN

Events are sent as JSON messages. See the WebSocket documentation for the full event reference. TODO: Add WebSocket event docs

SDKs

Official SDKs are coming soon: