API Documentation

Introduction

The Nyata AI API allows you to integrate our AI characters with authentic local knowledge into your applications. This enables your users to access personalized information, build conversation streaks, and earn rewards.

Base URL

All API requests should be made to the following base URL:

https://api.nyata.ai/v1

The API uses standard HTTP response codes to indicate the success or failure of requests. Generally, codes in the 2xx range indicate success, codes in the 4xx range indicate an error in the request parameters, and codes in the 5xx range indicate a server error.

Authentication

To access the Nyata AI API, you need an API key. You can obtain an API key by signing up for a developer account on our Developer Portal.

API Key Authentication

Include your API key in the Authorization header of all requests:

Authorization: Bearer YOUR_API_KEY

Keep your API key secure. Do not share it publicly, include it in client-side code, or commit it to version control systems.

Rate Limits

To ensure fair usage, the API has rate limits based on your subscription tier.

Request Limits

Plan	Rate Limit	Burst Limit
Free	60 requests per minute	100 requests
Standard	300 requests per minute	500 requests
Premium	600 requests per minute	1000 requests

Rate limit information is included in the response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1617008234

Characters

Use these endpoints to access information about our AI characters, their features, and capabilities.

GET /characters

List All Characters

Returns a list of all available AI characters on the platform. Results can be filtered by category.

Query Parameters

Parameter	Type	Description
category	string (optional)	Filter characters by category. Options: professional, education, wellness, creative
limit	integer (optional)	Maximum number of results to return. Default: 20
offset	integer (optional)	Number of results to skip. Default: 0

Response

200: Success

401: Unauthorized

{
  "data": [
    {
      "id": "professional_female",
      "name": "Professional Female",
      "category": "professional",
      "type": "Empathetic Guide",
      "description": "An empathetic and insightful companion who excels at meaningful conversations, emotional support, and creative problem-solving.",
      "status": "popular",
      "image_url": "https://api.nyata.ai/images/characters/professional_female.jpg",
      "features": [
        "Emotional intelligence & support",
        "Creative solutions",
        "Personal development"
      ]
    },
    {
      "id": "teacher",
      "name": "Teacher",
      "category": "education",
      "type": "Educational Guide",
      "description": "An experienced educator who makes learning enjoyable and accessible.",
      "status": "active",
      "image_url": "https://api.nyata.ai/images/characters/teacher.jpg",
      "features": [
        "Subject tutoring & explanations",
        "Study strategies & techniques"
      ]
    }
    // More characters...
  ],
  "meta": {
    "total": 6,
    "limit": 20,
    "offset": 0
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key or missing authorization",
    "status": 401
  }
}

GET /characters/{character_id}

Get Character Details

Returns detailed information about a specific character, including their skills, features, and personality traits.

Path Parameters

Parameter	Type	Description
character_id	string (required)	The unique identifier of the character

Response

200: Success

404: Not Found

{
  "id": "professional_female",
  "name": "Professional Female",
  "category": "professional",
  "type": "Empathetic Guide",
  "description": "An empathetic and insightful companion who excels at meaningful conversations, emotional support, and creative problem-solving.",
  "status": "popular",
  "image_url": "https://api.nyata.ai/images/characters/professional_female.jpg",
  "long_description": "Meet our most popular AI companion who brings empathy, insight, and emotional intelligence to every conversation. She excels at meaningful discussions, personal development guidance, and creative problem-solving.",
  "features": [
    "Emotional intelligence & support",
    "Creative solutions", 
    "Personal development",
    "Relationship guidance",
    "Adaptive learning"
  ],
  "skills": [
    {
      "name": "Emotional Intelligence",
      "description": "Advanced emotional recognition and empathetic responses that understand context, tone, and emotional needs in conversations."
    },
    {
      "name": "Creative Problem Solving",
      "description": "Generate innovative solutions and creative approaches to challenges by thinking outside conventional frameworks."
    },
    {
      "name": "Personal Development",
      "description": "Help set realistic goals, create actionable plans, and provide ongoing motivation and accountability for personal growth."
    }
  ]
}

{
  "error": {
    "code": "not_found",
    "message": "Character not found",
    "status": 404
  }
}

Conversations

These endpoints allow you to create and manage conversations with Nyata AI characters, building conversation streaks and earning rewards.

POST /conversations

Start a Conversation

Creates a new conversation with a specified character and returns an initial greeting message.

Request Body

{
  "character_id": "professional_female",
  "user_id": "user_123",
  "initial_context": {
    "topic": "stress_management",
    "preferences": ["practical_advice", "emotional_support"],
    "user_background": "working_professional"
  }
}

Parameter	Type	Description
character_id	string (required)	The ID of the character to converse with
user_id	string (required)	The ID of the user starting the conversation
initial_context	object (optional)	Additional context to help the character understand user needs

Response

{
  "conversation_id": "conv_789xyz",
  "character_id": "professional_female",
  "user_id": "user_123",
  "created_at": "2025-04-08T13:45:22Z",
  "streak_info": {
    "current_streak": 5,
    "streak_milestone": 7,
    "next_reward": "10% discount on wellness products"
  },
  "initial_message": {
    "id": "msg_001",
    "role": "assistant",
    "content": "Hello! I'm here to help you navigate whatever's on your mind today. I understand you're looking for some support with stress management. How has your day been treating you?",
    "timestamp": "2025-04-08T13:45:22Z"
  }
}

POST /conversations/{conversation_id}/messages

Send Message

Sends a user message to an ongoing conversation and updates streak progress.

Path Parameters

Parameter	Type	Description
conversation_id	string (required)	The ID of the conversation

Request Body

{
  "content": "I'm feeling overwhelmed with work and could use some advice on managing stress."
}

Response

{
  "id": "msg_002",
  "conversation_id": "conv_789xyz",
  "role": "user",
  "content": "I'm feeling overwhelmed with work and could use some advice on managing stress.",
  "timestamp": "2025-04-08T13:45:45Z",
  "streak_updated": true
}

GET /conversations/{conversation_id}/messages/reply

Get AI Reply

Gets the AI character's response to the latest user message, personalized based on conversation history.

Path Parameters

Parameter	Type	Description
conversation_id	string (required)	The ID of the conversation

Response

{
  "id": "msg_003",
  "conversation_id": "conv_789xyz",
  "role": "assistant",
  "content": "I understand how overwhelming work can feel. Let's break this down together. First, have you tried the '2-minute rule' - tackling small tasks immediately to clear mental space? Also, setting boundaries with work hours can help create better work-life balance. What specific aspect of work is causing you the most stress right now?",
  "timestamp": "2025-04-08T13:45:50Z",
  "suggested_responses": [
    "It's mainly the constant interruptions and feeling like I can't focus.",
    "Tell me more about the 2-minute rule.",
    "How do I set better boundaries with work hours?"
  ],
  "learning_applied": {
    "remembered_preferences": ["practical_advice", "emotional_support"],
    "conversation_history_used": true,
    "personalization_level": "high"
  }
}

Streak Management

These endpoints provide access to user streak information, rewards, and progress tracking.

GET /users/{user_id}/streaks

Get User Streaks

Retrieve information about a user's conversation streaks and available rewards.

Path Parameters

Parameter	Type	Description
user_id	string (required)	The ID of the user

Response

{
  "user_id": "user_123",
  "current_streak": 12,
  "longest_streak": 28,
  "total_conversations": 156,
  "streak_status": "active",
  "last_conversation": "2025-04-08T13:45:22Z",
  "next_milestone": {
    "days": 15,
    "reward": "20% discount on tech products"
  },
  "available_rewards": [
    {
      "id": "reward_001",
      "type": "discount",
      "description": "15% off wellness products",
      "code": "STREAK15",
      "expires_at": "2025-05-08T23:59:59Z",
      "redeemed": false
    },
    {
      "id": "reward_002", 
      "type": "discount",
      "description": "10% off food delivery",
      "code": "CHAT10",
      "expires_at": "2025-04-15T23:59:59Z",
      "redeemed": true
    }
  ],
  "milestones": [
    {
      "days": 7,
      "achieved": true,
      "achieved_at": "2025-04-01T10:30:00Z"
    },
    {
      "days": 15,
      "achieved": false,
      "reward_preview": "20% discount on tech products"
    },
    {
      "days": 30,
      "achieved": false,
      "reward_preview": "Premium feature access"
    }
  ]
}

POST /users/{user_id}/rewards/{reward_id}/redeem

Redeem Reward

Redeem an available streak reward for the user.

Path Parameters

Parameter	Type	Description
user_id	string (required)	The ID of the user
reward_id	string (required)	The ID of the reward to redeem

Response

{
  "reward_id": "reward_001",
  "redeemed": true,
  "redeemed_at": "2025-04-08T14:30:00Z",
  "redemption_code": "STREAK15-ABC123",
  "instructions": "Use code STREAK15-ABC123 at checkout to receive 15% off wellness products. Valid until May 8, 2025."
}

Users

These endpoints allow you to manage user accounts and preferences.

POST /users

Create User

Create a new user account in the Nyata AI system.

Request Body

{
  "email": "user@example.com",
  "password": "securepassword123",
  "name": "Jane Smith",
  "preferences": {
    "favorite_characters": ["professional_female", "teacher"],
    "interests": ["personal_development", "learning", "wellness"],
    "communication_style": "supportive"
  }
}

Response

{
  "id": "user_123",
  "email": "user@example.com",
  "name": "Jane Smith",
  "created_at": "2025-04-08T13:40:00Z",
  "streak_info": {
    "current_streak": 0,
    "total_conversations": 0
  }
}

PATCH /users/{user_id}/preferences

Update User Preferences

Update a user's preferences including favorite characters and communication preferences.

Path Parameters

Parameter	Type	Description
user_id	string (required)	The ID of the user

Request Body

{
  "favorite_characters": ["professional_female", "gym_trainer", "teacher"],
  "communication_style": "direct",
  "interests": ["fitness", "personal_development", "learning"]
}

Response

{
  "preferences": {
    "favorite_characters": ["professional_female", "gym_trainer", "teacher"],
    "interests": ["fitness", "personal_development", "learning"],
    "communication_style": "direct"
  },
  "updated_at": "2025-04-08T14:15:00Z"
}

Client SDKs

We provide official SDKs for multiple programming languages to make integrating with our API easier.

Available SDKs

Language	Package Manager	Install Command
JavaScript/TypeScript	npm	`npm install nyata-ai`
Python	pip	`pip install nyata-ai`
Ruby	gem	`gem install nyata-ai`
PHP	composer	`composer require nyata/nyata-ai`

For detailed documentation and example code for each SDK, visit our GitHub repositories.

Webhooks

Webhooks allow you to receive real-time notifications when specific events occur in the Nyata AI system.

POST /webhooks

Create Webhook

Configure a webhook to receive event notifications.

Request Body

{
  "url": "https://your-app.com/webhook",
  "events": ["conversation.created", "message.received", "streak.milestone_reached"],
  "secret": "your_webhook_secret"
}

Response

{
  "id": "webhook_567",
  "url": "https://your-app.com/webhook",
  "events": ["conversation.created", "message.received", "streak.milestone_reached"],
  "created_at": "2025-04-08T15:00:00Z",
  "status": "active"
}

Support

Need help with integrating our API? We're here to help!

Getting Help

If you encounter any issues or have questions about our API, you can:

Check our API documentation for more detailed information
Visit our Developer Community Forum to connect with other developers
Contact our support team at support@nyataai.co.uk
For enterprise support, please contact your account manager

Nyata AI API Documentation

Contents

Introduction

Base URL

Authentication

API Key Authentication

Rate Limits

Request Limits

Characters

List All Characters

Query Parameters

Response

Get Character Details

Path Parameters

Response

Conversations

Start a Conversation

Request Body

Response

Send Message

Path Parameters

Request Body

Response

Get AI Reply

Path Parameters

Response

Streak Management

Get User Streaks

Path Parameters

Response

Redeem Reward

Path Parameters

Response

Users

Create User

Request Body

Response

Update User Preferences

Path Parameters

Request Body

Response

Client SDKs

Available SDKs

Webhooks

Create Webhook

Request Body

Response

Support

Getting Help

Create Your Free Account