Build with hyper-local community AI

Overview

The Nyata AI API gives your application the same local knowledge that powers the Nyata app. Send a question in plain words and get back a reply, plus the live listings behind it: services from verified local organisations and community events, with days, times and addresses.

Endpoint

POST https://nyataai.co.uk/external_api.php

Authentication

X-API-Key header

Format

JSON over HTTPS

Version

v1.1

Coverage

One API for every city. Live listings roll out city by city; pass city or location to scope results.

Quickstart

Make your first request in a few minutes. Each quickstart is a single file with nothing to install.

nyata-starter-kit/
├── README.md
├── .env.example
├── .gitignore
├── bash/quickstart.sh
├── windows/quickstart.ps1
├── python/quickstart.py
├── node/quickstart.mjs
├── postman/
│   └── nyata-api.postman_collection.json
└── spec/
    └── nyata-api.spec.yaml

1. Get your API key

   Copy it from your API dashboard. No key yet? Buy a plan or redeem a trial code.

2. Unzip the kit and add your key

   Copy .env.example to .env, then paste your key after NYATA_API_KEY=.

   Terminal Copy

   # macOS / Linux
   cp .env.example .env
   
   # Windows
   copy .env.example .env
   

   Prefer environment variables? Set NYATA_API_KEY instead. It takes priority over .env.

3. Run the quickstart for your platform

   macOS / Linux Windows Python Node.js

   Needs curl, which comes with macOS and most Linux distributions. Also works in WSL and Git Bash.

   Terminal Copy

   cd nyata-starter-kit
   bash bash/quickstart.sh "Where can I find a food bank?"
   

   Download quickstart.sh

   View the full script bash/quickstart.sh, 144 lines

   bash/quickstart.sh Copy

   #!/usr/bin/env bash
   #
   # Nyata AI API - quickstart for macOS, Linux, WSL and Git Bash
   #
   # Usage (from the starter-kit folder):
   #   bash bash/quickstart.sh "Where can I find a food bank?"
   #
   # Needs curl. If python3 or jq is installed, only the reply text is printed;
   # otherwise you'll see the full JSON response.
   #
   # Your API key is read from the NYATA_API_KEY environment variable, or from a
   # .env file in the current folder or the starter-kit folder.
   
   set -euo pipefail
   
   DEFAULT_API_URL="https://nyataai.co.uk/external_api.php"
   DEFAULT_MODEL="nyata-1"
   DASHBOARD_URL="https://app.nyataai.co.uk/developers"
   MAX_RETRIES=4
   
   KIT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
   
   # Read KEY=VALUE lines from a .env file. Variables that are already set win.
   load_env() {
     local file="$1" line key value
     local pattern='^[[:space:]]*(export[[:space:]]+)?([A-Za-z_][A-Za-z0-9_]*)[[:space:]]*=[[:space:]]*(.*)$'
     local double_quoted='^"(.*)"$'
     local single_quoted="^'(.*)'\$"
     [[ -f "$file" ]] || return 0
     while IFS= read -r line || [[ -n "$line" ]]; do
       line="${line%$'\r'}"
       [[ "$line" =~ $pattern ]] || continue
       key="${BASH_REMATCH[2]}"
       value="${BASH_REMATCH[3]}"
       value="${value%"${value##*[![:space:]]}"}"
       if [[ "$value" =~ $double_quoted || "$value" =~ $single_quoted ]]; then
         value="${BASH_REMATCH[1]}"
       fi
       if [[ -z "${!key:-}" ]]; then
         export "$key=$value"
       fi
     done < "$file"
   }
   
   load_env "$PWD/.env"
   load_env "$KIT_DIR/.env"
   
   API_URL="${NYATA_API_URL:-$DEFAULT_API_URL}"
   MODEL="${NYATA_MODEL:-$DEFAULT_MODEL}"
   API_KEY="${NYATA_API_KEY:-}"
   QUESTION="${*:-Where can I get a free meal today?}"
   
   if [[ -z "$API_KEY" || "$API_KEY" == "your_api_key" ]]; then
     echo "Add your API key first: copy .env.example to .env and paste your key," >&2
     echo "or run: export NYATA_API_KEY=\"your_api_key\"" >&2
     exit 1
   fi
   
   if ! command -v curl >/dev/null 2>&1; then
     echo "This script needs curl. Install it, then try again." >&2
     exit 1
   fi
   
   # Turn a string into a JSON string literal without extra tools.
   json_string() {
     local s
     s="$(printf '%s' "$1" | tr -d '\001-\010\013\014\016-\037')"
     s="${s//\\/\\\\}"
     s="${s//\"/\\\"}"
     s="${s//$'\n'/\\n}"
     s="${s//$'\r'/\\r}"
     s="${s//$'\t'/\\t}"
     printf '"%s"' "$s"
   }
   
   BODY="{\"model\":$(json_string "$MODEL"),\"messages\":[{\"role\":\"user\",\"content\":$(json_string "$QUESTION")}],\"max_tokens\":300,\"temperature\":0.7}"
   
   RESPONSE_FILE="$(mktemp)"
   HEADERS_FILE="$(mktemp)"
   trap 'rm -f "$RESPONSE_FILE" "$HEADERS_FILE"' EXIT
   
   attempt=0
   while true; do
     if ! status="$(curl -sS "$API_URL" \
         -H "Content-Type: application/json" \
         -H "X-API-Key: $API_KEY" \
         -A "nyata-starter-kit/1.0 (bash)" \
         --max-time 30 \
         --data-binary "$BODY" \
         -D "$HEADERS_FILE" -o "$RESPONSE_FILE" -w '%{http_code}')"; then
       echo "Network error: could not reach $API_URL" >&2
       exit 1
     fi
   
     # Retry rate limits (429) and server errors (5xx) with backoff.
     if [[ "$status" == "429" || "$status" == 5* ]] && (( attempt < MAX_RETRIES )); then
       delay="$(awk 'tolower($1) == "retry-after:" { gsub(/\r/, "", $2); print $2 }' "$HEADERS_FILE" | tail -n 1)"
       if ! [[ "$delay" =~ ^[0-9]+$ ]]; then
         delay=$(( 1 << attempt ))
       fi
       if (( delay > 60 )); then
         delay=60
       fi
       echo "HTTP $status - retrying in ${delay}s..." >&2
       sleep "$delay"
       attempt=$(( attempt + 1 ))
       continue
     fi
     break
   done
   
   if [[ "$status" == "200" ]]; then
     if command -v python3 >/dev/null 2>&1 &&
        PYTHONIOENCODING=utf-8 python3 -c 'import json, sys; print(json.load(sys.stdin)["choices"][0]["message"]["content"])' < "$RESPONSE_FILE" 2>/dev/null; then
       exit 0
     fi
     if command -v jq >/dev/null 2>&1 && jq -er '.choices[0].message.content' < "$RESPONSE_FILE" 2>/dev/null; then
       exit 0
     fi
     cat "$RESPONSE_FILE"
     echo
     exit 0
   fi
   
   case "$status" in
     400) message="Bad request - check the model name and message format." ;;
     401) message="Invalid or missing API key - check NYATA_API_KEY." ;;
     403)
       if grep -q "quota_exceeded" "$RESPONSE_FILE"; then
         message="Monthly quota used up - check $DASHBOARD_URL or upgrade your plan."
       else
         message="This API key doesn't have access to the API."
       fi
       ;;
     429) message="Too many requests - slow down and try again shortly." ;;
     5??) message="Nyata AI had a problem handling the request - try again in a moment." ;;
     *) message="Unexpected response." ;;
   esac
   
   echo "Error $status: $message" >&2
   if [[ -s "$RESPONSE_FILE" ]]; then
     echo "Response: $(head -c 500 "$RESPONSE_FILE")" >&2
   fi
   exit 1
   

   The reply is printed in your terminal. If something goes wrong, the script explains the error and what to do about it.

Authentication

Every request needs your API key in the X-API-Key header.

Find your key on your API dashboard. New to Nyata? Get a key: you'll create an account, then buy a plan or redeem a free-trial code. The examples on this page read your key from the NYATA_API_KEY environment variable.

Endpoint

All requests go to one endpoint:

Always use HTTPS, and send the request body as JSON.

Request

Send a JSON body with these parameters:

Message objects

Example body

{
  "model": "nyata-1",
  "messages": [
    { "role": "user", "content": "Where can I get a free lunch today?" }
  ],
  "location": { "latitude": 51.45, "longitude": -2.58 },
  "max_tokens": 300,
  "temperature": 0.7
}

Response

A successful request returns 200 and a JSON object:

{
  "id": "nyata-abc123",
  "object": "nyata.answer",
  "created": 1793500000,
  "model": "nyata-1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Alright my lover! Community Lunch Club is on today from 12:00 to 14:00..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 410, "completion_tokens": 96, "total_tokens": 506 },
  "api_usage": { "requests_used": 4, "requests_limit": 1000, "requests_remaining": 996 },
  "nyata": {
    "model": "nyata-1",
    "founder": "Ibrahim Maina",
    "version": "1.1",
    "results": [
      {
        "type": "charity_service",
        "id": 10,
        "name": "Community Lunch Club",
        "organisation": "Example Community Kitchen",
        "organisation_type": "charity",
        "verification": "verified",
        "service_type": "meals",
        "day": "Saturday",
        "next_date": "2026-10-31",
        "start_time": "12:00",
        "end_time": "14:00",
        "open_now": false,
        "meal_period": "lunch",
        "booking_required": false,
        "address": "1 Example Street",
        "postcode": "AB1 2CD",
        "distance_km": 0.4,
        "directions_url": "https://www.google.com/maps/search/?api=1&query=51.45,-2.58"
      }
    ]
  }
}

Live results

Nyata answers from live listings: services run by verified local organisations and community events listed on Nyata. Every response includes the listings behind the answer in nyata.results, so you can show them as cards, a list or pins on a map. The reply text only recommends places that appear in those results.

What's covered

• Charity and community services (charity_service): free meals and food, showers, shelter, clothing, healthcare, support groups, employment help and emergency support.
• Events and offers (event): community events, workshops, celebrations, local offers and discounts.
• Coming next: local services such as barbers, beauty, cleaning and taxis.

Only approved, active listings are returned, with public details only. The API is for discovery: it tells people where to go and when, and bookings stay with the organisation or in the Nyata app.

Service fields

Event fields

Fields without a value are left out, so check that a field exists before you use it. New fields may be added in future versions without notice; existing ones won't be removed or renamed without advance notice.

Example: list the results

const data = await response.json();
const reply = data.choices[0].message.content;   // the answer, as text
const results = data.nyata?.results ?? [];       // the listings behind it

for (const item of results) {
  if (item.type === "charity_service") {
    console.log(`${item.name} (${item.organisation}): ${item.day} ${item.start_time}-${item.end_time}, ${item.address}`);
  } else if (item.type === "event") {
    console.log(`${item.title}: ${item.starts}${item.location ? ", " + item.location : ""}`);
  }
}

Code examples

Any HTTP client works. Each example reads your key from the NYATA_API_KEY environment variable.

curl https://nyataai.co.uk/external_api.php \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $NYATA_API_KEY" \
  -d '{
    "model": "nyata-1",
    "messages": [{ "role": "user", "content": "Where can I find a food bank?" }],
    "max_tokens": 300
  }'

// Node.js 18+, on your server. Never expose your API key in browser code.
const response = await fetch('https://nyataai.co.uk/external_api.php', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.NYATA_API_KEY,
  },
  body: JSON.stringify({
    model: 'nyata-1',
    messages: [{ role: 'user', content: 'Where can I find a food bank?' }],
    max_tokens: 300,
  }),
});

if (!response.ok) {
  throw new Error(`Nyata API error ${response.status}: ${await response.text()}`);
}

const data = await response.json();
console.log(data.choices[0].message.content);

# pip install requests
import os

import requests

response = requests.post(
    "https://nyataai.co.uk/external_api.php",
    headers={"X-API-Key": os.environ["NYATA_API_KEY"]},
    json={
        "model": "nyata-1",
        "messages": [{"role": "user", "content": "Where can I find a food bank?"}],
        "max_tokens": 300,
    },
    timeout=30,
)
response.raise_for_status()
print(response.json()["choices"][0]["message"]["content"])

<?php
$ch = curl_init('https://nyataai.co.uk/external_api.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: ' . getenv('NYATA_API_KEY'),
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'model' => 'nyata-1',
        'messages' => [['role' => 'user', 'content' => 'Where can I find a food bank?']],
        'max_tokens' => 300,
    ]),
]);

$body = curl_exec($ch);
if ($body === false) {
    throw new RuntimeException('Could not reach the Nyata API: ' . curl_error($ch));
}

$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status !== 200) {
    throw new RuntimeException("Nyata API error $status: $body");
}

$data = json_decode($body, true);
echo $data['choices'][0]['message']['content'], PHP_EOL;

Errors

The API uses standard HTTP status codes.

Rate limits and retries

Every plan has a monthly request allowance, shown under Pricing, plus a short-term rate limit that keeps the API responsive for everyone.

Recommended retry strategy

• On 429, wait for the number of seconds in the Retry-After header, then retry.
• For repeated 429 or 5xx responses, back off exponentially: 1s, 2s, 4s, 8s.
• On 403 with quota_exceeded, stop retrying and check your dashboard for your remaining quota and reset date.

The starter-kit scripts already follow this strategy, so you can copy their ask() helpers into your own project.

Versioning

The current API version is v1.1. The model string is versioned separately from the API itself.

Changelog

• v1.1 (31 October 2026): answers now come from live listings of verified local organisations and community events; every response includes them in nyata.results; new optional location and city request fields; the model identifier is now nyata-1 (the previous identifier still works); the object field now reads nyata.answer. Existing integrations keep working.
• v1.0: first release.

We'll give advance notice before any breaking change to the endpoint, the request format or the model identifier, so you have time to update your integration.

Use with AI assistants (MCP)

Nyata runs a remote Model Context Protocol server. Connect it to Claude, ChatGPT, Cursor, VS Code, Windsurf, Gemini CLI, Codex or any other app that supports remote MCP, and the assistant can search Nyata's live listings as tools: community support, local services, events and provider details.

Transport

Streamable HTTP

Sign-in

Sign in with a Nyata account (OAuth 2.1 with PKCE). Clients register automatically, so there's no client ID to set up.

API key

Or send your Nyata API key as Authorization: Bearer for server-to-server use. MCP with an API key is part of the Premium and Enterprise plans; keys created before 8 November 2026 keep the access they already had.

Plans

Premium: the MCP tools with live data; newly approved organisations are added at the weekly update (Mondays). Enterprise: the latest MCP with early access to new tools, new organisations the moment they're approved, a whats_new feed, open-now and nearest-first search, and up to 50 results. Events, times and closures are live on every plan.

Access

Read-only. The tools find and describe listings; they don't book, pay or post.

Claude (web, desktop and mobile)

1. In Claude, add a custom connector and paste https://mcp.nyataai.co.uk/mcp as the server URL. There's no client ID or secret to enter.
2. Click Connect and sign in to your Nyata account, then approve access.
3. Ask a local question in any chat, for example “Where's open for a free meal near me tonight?”

Once added, the connector works across Claude on web, desktop and mobile. Claude's free plan allows one custom connector. On Team and Enterprise plans, an owner adds it for the organisation and each member connects with their own Nyata account.

Claude plugin

The Nyata plugin bundles the connector with guidance on answering local questions safely (999 first in an emergency). It holds no keys or secrets: everyone signs in with their own Nyata account.

1. Download the Nyata plugin (.zip). Keep it zipped.
2. In Claude, open Customize, then Plugins, choose Add and upload the zip.
3. Open the plugin, go to its Connectors tab, click Connect and sign in with your Nyata account.

An uploaded plugin is added to your own account only. If you've already added the custom connector above, remove it so Nyata isn't connected twice.

Claude Code

Add the server, then run /mcp inside Claude Code to sign in with your Nyata account:

claude mcp add --transport http nyata https://mcp.nyataai.co.uk/mcp

To use an API key instead of signing in:

claude mcp add --transport http nyata https://mcp.nyataai.co.uk/mcp \
  --header "Authorization: Bearer $NYATA_API_KEY"

ChatGPT

1. In ChatGPT on the web, open Settings, then Apps & Connectors, then Advanced, and turn on Developer mode.
2. Back in Apps & Connectors, choose Create. Name it Nyata, paste https://mcp.nyataai.co.uk/mcp as the server URL and choose OAuth.
3. Sign in with your Nyata account when asked, then pick Nyata from the + menu in a new chat.

Developer mode is available on ChatGPT's paid plans; on Business and Enterprise an admin may need to allow custom connectors. ChatGPT moves this setting from time to time, so check under Settings if it isn't where described.

Cursor

Add Nyata to Cursor

Or add it to ~/.cursor/mcp.json. Cursor asks you to sign in with Nyata the first time it connects.

{
  "mcpServers": {
    "nyata": {
      "url": "https://mcp.nyataai.co.uk/mcp"
    }
  }
}

VS Code (GitHub Copilot)

Install in VS Code

Or add it to .vscode/mcp.json in your project, then click Start above the server and allow the Nyata sign-in.

{
  "servers": {
    "nyata": {
      "type": "http",
      "url": "https://mcp.nyataai.co.uk/mcp"
    }
  }
}

Windsurf

In the Cascade panel, open MCPs, choose View raw config and add Nyata, then refresh. Cascade opens the Nyata sign-in on first use.

{
  "mcpServers": {
    "nyata": {
      "serverUrl": "https://mcp.nyataai.co.uk/mcp"
    }
  }
}

Gemini CLI

Add the server, then run /mcp auth nyata inside Gemini CLI to sign in:

gemini mcp add --transport http nyata https://mcp.nyataai.co.uk/mcp

Codex

Add the server, then sign in:

codex mcp add nyata --url https://mcp.nyataai.co.uk/mcp
codex mcp login nyata

Any other MCP app

Nyata works with any app that supports remote MCP servers over Streamable HTTP with OAuth. Give it the server URL and sign in with your Nyata account when asked, or send your API key as Authorization: Bearer if the app only supports headers.

Tools

Downloads

The starter kit contains everything below. You can also download each file on its own.

• Starter kitAll quickstarts, the Postman collection, the API spec and a settings template. .zip
• Postman collectionImport into Postman, set the apiKey variable, then send. .json
• API specFor Insomnia, Bruno, Swagger UI or your code generator. .yaml
• Bash quickstartmacOS, Linux, WSL and Git Bash. .sh
• PowerShell quickstartWindows PowerShell 5.1 and PowerShell 7. .ps1
• Python quickstartPython 3.8+, standard library only. .py
• Node.js quickstartNode.js 18+, no dependencies. .mjs

Support

Email support@nyataai.co.uk with the time of the request, the endpoint, the status code and the response body. Never include your full API key.

Answers to common questions are in the Help Center and FAQs.