Getting Started

Base URL

All API requests should be made to:

https://api.relativum.com/v1

Authentication

All API requests require authentication using a Bearer token:

Authorization: Bearer your_api_token_here

Rate Limits

All API endpoints are rate-limited to:

• 10 requests per second
• Burst limit: 20 requests
• Reset window: 1 second

When exceeded, returns 429 Too Many Requests:

{
  "error": "Rate limit exceeded",
  "reset_at": "2024-01-20T12:00:00Z",
  "retry_after": 0.5
}

Error Handling

Standard HTTP response codes with detailed messages:

{
  "error": "Error message here",
  "code": "ERROR_CODE",
  "details": {
    "field": "Additional error context"
  }
}

Common status codes:

• 400: Bad Request
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 429: Too Many Requests
• 500: Internal Server Error

Insights

Upload Insight

POST /v1/insights/upload

Request Schema

{
  "content": "Your insight or feedback text here",
  "organization_id": "your_organization_uuid",
  "warehouse_id": "ABCDEF",  // Optional, 6-character warehouse ID
  "is_image": false,
  "metadata": {
    "source": "email",
    "category": "feedback",
    "custom_field": "value"
  },
  "people": {
    "has_id": false,
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "+1234567890"
  }
}

Response Format

{
  "message": "Your insight has been uploaded successfully!",
  "insightId": "uuid",
  "analysis": {
    "summary": "Brief summary of the insight",
    "sentiment": "positive",
    "criticality": 0.75,
    "topics": ["UX", "Performance"],
    "entities": ["Dashboard", "API"]
  }
}

Search

Unified Search

POST /v1/search

Search Parameters

{
  "query": "customer retention strategies",
  "organizationId": "your_organization_uuid",
  "userId": "your_user_uuid",
  "skip": 0,
  "take": 10,  // Maximum 25
  "include": ["insights", "people", "clusters"],
  "filters": {
    "date_range": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-31T23:59:59Z"
    },
    "sentiment": ["positive", "negative"],
    "criticality": {
      "min": 0.7,
      "max": 1.0
    },
    "metadata": {
      "source": ["email", "survey"],
      "category": "feedback"
    }
  }
}

Search Response

{
  "results": [
    {
      "id": "uuid",
      "type": "insight",
      "summary": "Content summary",
      "relevance": 0.923,
      "highlights": [
        {
          "field": "content",
          "snippet": "...improved customer retention by implementing...",
          "positions": [[10, 28]]
        }
      ]
    }
  ],
  "pagination": {
    "skip": 0,
    "take": 10,
    "total": 45,
    "hasMore": true
  }
}

Clusters

List Clusters

GET /v1/clusters/list

Query Parameters:

• organization_id (required)
• skip (default: 0)
• take (default: 10, max: 25)
• include_archived (default: false)

{
  "results": [
    {
      "id": "uuid",
      "cluster_name": "Customer Retention Issues",
      "summary": "Collection of insights about retention challenges",
      "key_insights": [
        "Users requesting better onboarding",
        "Price concerns from enterprise segment"
      ],
      "sentiment_overall": "Negative",
      "date_created": "2023-07-01T00:00:00Z",
      "is_singleton": false
    }
  ],
  "pagination": {
    "skip": 0,
    "take": 10,
    "total": 25,
    "hasMore": true
  }
}

Get Cluster History

GET /v1/clusters/:cluster_id/history

Query Parameters:

• organization_id (required)

{
  "history": [
    {
      "cluster_id": "uuid",
      "insight_id": "uuid",
      "date_added": "2024-01-15T10:30:00Z",
      "insights": {
        "summary": "User feedback about mobile app",
        "content": "Original insight content",
        "criticality": 0.8
      }
    }
  ]
}

Archive Cluster

POST /v1/clusters/archive

{
  "cluster_id": "uuid",
  "organization_id": "uuid"
}

Delete Cluster

DELETE /v1/clusters/delete

{
  "cluster_id": "uuid",
  "organization_id": "uuid"
}

People

Create/Update Person

POST /v1/people/create

{
  "organization_id": "uuid",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "phone": "+1234567890",
  "demographics": {
    "age": "25-34",
    "gender": "male",
    "location": "New York",
    "incomeLevel": "mid",
    "company": "Acme Inc"
  },
  "customer_preferences": ["Mobile app", "Dark mode"],
  "behaviours": ["Regular feedback provider"],
  "metadata": {
    "source": "website_signup",
    "plan": "enterprise"
  }
}

List People

GET /v1/people/list

Query Parameters:

• organization_id (required)
• skip (default: 0)
• take (default: 10, max: 25)

{
  "results": [
    {
      "id": "uuid",
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "demographics": {
        "age": "25-34",
        "location": "New York"
      },
      "created_at": "2023-06-01T00:00:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "skip": 0,
    "take": 10,
    "total": 100,
    "hasMore": true
  }
}

Delete Person

DELETE /v1/people/delete

{
  "person_id": "uuid",
  "organization_id": "uuid"
}

Warehouses

List Warehouses

POST /v1/warehouses/list

{
  "organization_id": "uuid",
  "skip": 0,
  "take": 10
}

Create Warehouse

POST /v1/warehouses/create

{
  "organization_id": "uuid",
  "warehouse_id": "ABC123",
  "name": "Q3 Feedback",
  "description": "Q3 customer feedback collection",
  "is_default": false
}

Delete Warehouse

DELETE /v1/warehouses/delete

{
  "organization_id": "uuid",
  "warehouse_id": "ABC123"
}

Note: Only organization admins can delete warehouses, and the default warehouse cannot be deleted.