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 as a chat message and get back a reply in the familiar chat-completions format.

Endpoint

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

Authentication

X-API-Key header

Format

JSON, OpenAI-compatible

Version

v1.0

Coverage

Local service data currently covers Bristol, UK

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
└── openapi/
    └── nyata-api.openapi.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="ft:gpt-4.1-mini-2025-04-14:nyata:bristol:ChciyaQP"
   DASHBOARD_URL="https://nyataai.co.uk/api_dashboard.php"
   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? 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": "ft:gpt-4.1-mini-2025-04-14:nyata:bristol:ChciyaQP",
  "messages": [
    { "role": "user", "content": "Where can I find a food bank?" }
  ],
  "max_tokens": 300,
  "temperature": 0.7
}

Response

A successful request returns 200 and an OpenAI-compatible JSON object:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1733500000,
  "model": "ft:gpt-4.1-mini-2025-04-14:nyata:bristol:ChciyaQP",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "There are several food banks you can use this week..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  }
}

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": "ft:gpt-4.1-mini-2025-04-14:nyata:bristol:ChciyaQP",
    "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: 'ft:gpt-4.1-mini-2025-04-14:nyata:bristol:ChciyaQP',
    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": "ft:gpt-4.1-mini-2025-04-14:nyata:bristol:ChciyaQP",
        "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' => 'ft:gpt-4.1-mini-2025-04-14:nyata:bristol:ChciyaQP',
        '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.0. The model string is versioned separately from the API itself.

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.

Downloads

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

• Starter kitAll quickstarts, the Postman collection, the OpenAPI spec and a settings template. .zip
• Postman collectionImport into Postman, set the apiKey variable, then send. .json
• OpenAPI 3.0 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.