Get the App

Nyata AI API Documentation

Integrate our AI characters with Bristol accents and local knowledge into your applications

Contents

Introduction

The Nyata AI API allows you to integrate our AI characters with authentic Bristol accents and local knowledge into your applications. This enables your users to access information about Bristol's neighborhoods, events, support services, and more.

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: community, student, history, wellness
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": "brenda", "name": "Brenda", "category": "community", "type": "Community Guide", "description": "A friendly community guide with extensive knowledge of Bristol's neighborhoods, resources, and services.", "status": "popular", "image_url": "https://api.nyata.ai/images/characters/brenda.jpg", "features": [ "Local resources database", "Cost of living support", "Bristol neighborhood knowledge" ] }, { "id": "jack", "name": "Jack", "category": "student", "type": "Student Life", "description": "A helpful companion for university students in Bristol, offering guidance on accommodation, student discounts, social activities, and academic resources.", "status": "new", "image_url": "https://api.nyata.ai/images/characters/jack.jpg", "features": [ "Campus navigation", "Student deals finder" ] } // 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 dialect examples.

Path Parameters

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

Response

200: Success
404: Not Found
{ "id": "brenda", "name": "Brenda", "category": "community", "type": "Community Guide", "description": "A friendly community guide with extensive knowledge of Bristol's neighborhoods, resources, and services to help residents navigate daily life.", "status": "popular", "image_url": "https://api.nyata.ai/images/characters/brenda.jpg", "long_description": "Meet Brenda, our most popular AI companion who speaks with an authentic Bristol accent and has extensive knowledge of local resources, events, and support services. Brenda was designed to help residents navigate life in Bristol with a friendly, approachable personality and practical advice.", "features": [ "Local resources database", "Cost of living support", "Bristol neighborhood knowledge", "Public transportation guidance", "Events and activities calendar" ], "skills": [ { "name": "Local Navigation", "description": "Help you navigate Bristol's neighborhoods, find shortcuts, and provide directions to landmarks using local references rather than just street names." }, { "name": "Support Services", "description": "Connect you with relevant local support services, community resources, and assistance programs based on your specific needs." }, { "name": "Event Recommendations", "description": "Discover local events, festivals, and activities that match your interests, with details on timing, location, cost, and accessibility." } ], "dialect_samples": [ "Alright my lover!", "That's proper gert lush.", "Where's that to?" ] }
{ "error": { "code": "not_found", "message": "Character not found", "status": 404 } }

Conversations

These endpoints allow you to create and manage conversations with Nyata AI characters.

POST /conversations

Start a Conversation

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

Request Body

{ "character_id": "brenda", "user_id": "user_123", "initial_context": { "location": "Stokes Croft, Bristol", "preferences": ["affordable", "vegetarian"], "query_type": "food_recommendation" } }
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": "brenda", "user_id": "user_123", "created_at": "2025-04-08T13:45:22Z", "initial_message": { "id": "msg_001", "role": "assistant", "content": "Alright my lover! I'm Brenda, your Bristol AI companion. How can I help you find some good affordable veggie food around Stokes Croft today?", "timestamp": "2025-04-08T13:45:22Z" } }
POST /conversations/{conversation_id}/messages

Send Message

Sends a user message to an ongoing conversation.

Path Parameters

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

Request Body

{ "content": "I'm looking for affordable food options near Stokes Croft." }

Response

{ "id": "msg_002", "conversation_id": "conv_789xyz", "role": "user", "content": "I'm looking for affordable food options near Stokes Croft.", "timestamp": "2025-04-08T13:45:45Z" }
GET /conversations/{conversation_id}/messages/reply

Get AI Reply

Gets the AI character's response to the latest user message.

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": "Proper job for choosing Stokes Croft! That area's gert lush for affordable food. You've got Poco for tapas, Caribbean Croft for Jamaican, and The Canteen for good value meals with live music. If you're really watching the pennies, check out Biblos for their wraps or the weekly community feast at Hamilton House where you can pay what you feel. Shall I send you the locations for any of these?", "timestamp": "2025-04-08T13:45:50Z", "suggested_responses": [ "Yes, send me the location for The Canteen please.", "Tell me more about Hamilton House.", "Which of these has the best vegetarian options?" ], "entities": { "locations": [ { "name": "Poco", "type": "restaurant", "cuisine": "tapas", "coordinates": { "lat": 51.4623, "long": -2.5920 } } ] } }

Local Knowledge

These endpoints provide access to Bristol-specific information like local resources, events, and transport options.

GET /knowledge/resources

Search Resources

Search for local resources, services, venues, and other points of interest in Bristol.

Query Parameters

Parameter Type Description
query string (required) Search term (e.g., "vegetarian restaurants")
category string (optional) Resource category (e.g., food, healthcare, housing)
location string (optional) Bristol location or neighborhood
character_id string (optional) Get results in the style of a specific character

Response

{ "data": [ { "id": "resource_123", "name": "The Canteen", "category": "food", "address": "80 Stokes Croft, Bristol BS1 3QY", "description": "They do a bangin' meal deal with a main dish, two sides, and a drink for around £10, and they often have free live music in the evenings. They're also proper good for vegetarian and vegan options.", "coordinates": { "lat": 51.4631, "long": -2.5923 }, "attributes": { "price_range": "affordable", "dietary_options": ["vegetarian", "vegan"], "features": ["live music", "outdoor seating"] }, "hours": { "monday": "12:00-23:00", "tuesday": "12:00-23:00" }, "image_url": "https://api.nyata.ai/images/resources/canteen.jpg" } ], "meta": { "total": 15, "filtered": 5 } }
GET /knowledge/events

Get Events

Retrieve information about upcoming events in Bristol.

Query Parameters

Parameter Type Description
start_date date (optional) Filter events starting from this date (default: today)
end_date date (optional) Filter events until this date
category string (optional) Event category (music, art, community, food, etc.)
location string (optional) Bristol location or neighborhood
free_only boolean (optional) Filter only free events (default: false)

Response

{ "data": [ { "id": "event_456", "name": "Community Feast at Hamilton House", "category": "food", "description": "Weekly community meal where you can pay what you feel. All food is vegetarian with vegan options available.", "location": { "name": "Hamilton House", "address": "80 Stokes Croft, Bristol BS1 3QY", "coordinates": { "lat": 51.4631, "long": -2.5923 } }, "start_time": "2025-04-10T18:00:00Z", "end_time": "2025-04-10T20:00:00Z", "price_info": "Pay what you feel", "image_url": "https://api.nyata.ai/images/events/hamilton_feast.jpg" } ] }

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": ["brenda", "margaret"], "interests": ["history", "food", "arts"], "dietary_preferences": ["vegetarian"] } }

Response

{ "id": "user_123", "email": "user@example.com", "name": "Jane Smith", "created_at": "2025-04-08T13:40:00Z" }
PATCH /users/{user_id}/preferences

Update User Preferences

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

Path Parameters

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

Request Body

{ "favorite_characters": ["brenda", "jack", "margaret"], "dietary_preferences": ["vegetarian", "gluten_free"] }

Response

{ "preferences": { "favorite_characters": ["brenda", "jack", "margaret"], "interests": ["history", "food", "arts"], "dietary_preferences": ["vegetarian", "gluten_free"] }, "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"], "secret": "your_webhook_secret" }

Response

{ "id": "webhook_567", "url": "https://your-app.com/webhook", "events": ["conversation.created", "message.received"], "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:

Previous: Getting Started Next: Advanced Topics