Kedy API Documentation

01Kedy API overview

The Kedy API lets your application send a text request to NOVAQ. This guide covers creating an account, using your API key, sending your first request, and processing the response on your server. The examples follow the basic request format used in the Çiçekli Teknolig participant guide.

If this is your first request, start with the quickstart. See the API reference for request fields or troubleshooting to investigate a failure.

02Quickstart

1. Create an account and sign in at chat.kedy.dev.
2. Create an API key on the same platform.
3. Replace YOUR_API_KEY in the example below with your key to set it for your terminal session.
4. Run the request command. A successful request returns a JSON response in your terminal.

macOS / Linux

export KEDY_API_KEY="YOUR_API_KEY"

curl https://api.kedy.dev/v1/chat/completions \
  -H "Authorization: Bearer $KEDY_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 30 \
  -d '{"model":"novaq","messages":[{"role":"user","content":"Hello"}]}'

Windows · PowerShell

$env:KEDY_API_KEY = "YOUR_API_KEY"

$body = @{
  model = "novaq"
  messages = @(@{ role = "user"; content = "Hello" })
} | ConvertTo-Json -Depth 6

Invoke-RestMethod `
  -Uri "https://api.kedy.dev/v1/chat/completions" `
  -Method Post `
  -Headers @{ Authorization = "Bearer $env:KEDY_API_KEY" } `
  -ContentType "application/json" `
  -Body $body `
  -TimeoutSec 30

The macOS / Linux example requires cURL. The Windows example uses PowerShell’s built-in HTTP command. Change content to send your own text.

03API keys and authentication

An API key is the secret your application uses to access the Kedy API. Include it in the Authorization header of every request, preceded by Bearer and a space.

Authorization: Bearer YOUR_API_KEY

• Store the key in a server environment variable: KEDY_API_KEY.
• Keep it out of frontend JavaScript, mobile app bundles, and public repositories.
• The browser should call your backend, which then calls the Kedy API.
• Keep the key out of screenshots, logs, and prompts you share with development tools.

Local development files

If you use a .env file, exclude it from version control. Share only a placeholder in .env.example with your team.

.env
.env.*
!.env.example

KEDY_API_KEY=YOUR_API_KEY

04API reference

The examples on this page send a POST request with a JSON body to the endpoint below. The base URL is https://api.kedy.dev, the endpoint path is /v1/chat/completions, and the model ID is novaq.

{
  "model": "novaq",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ]
}

05Send a request with Node.js

This example uses built-in fetch in Node.js 22 or later and requires no package installation. Save it as request.mjs. Set your key in the same terminal session using the quickstart command, then run the file.

const apiKey = process.env.KEDY_API_KEY;
if (!apiKey) throw new Error('Set KEDY_API_KEY first.');

const response = await fetch('https://api.kedy.dev/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'novaq',
    messages: [{ role: 'user', content: 'Hello' }]
  }),
  signal: AbortSignal.timeout(30_000)
});

if (!response.ok) {
  throw new Error(`Kedy API returned HTTP ${response.status}.`);
}
const data = await response.json();
const reply = data.choices?.[0]?.message?.content;
if (typeof reply !== 'string' || !reply.trim()) {
  throw new Error('The response did not contain a text message.');
}
console.log(reply);

node request.mjs

The code checks that the key is present, sends the JSON request, treats unsuccessful HTTP statuses as errors, and validates that the response contains text. Connection failures or timeouts cause fetch to throw. Wrap the operation in your application’s error handling when integrating it.

06Send a request with Python

This example uses the Python 3 standard library and needs no additional packages. Save it as request.py and run it after setting your API key in the same terminal session.

import json
import os
import urllib.error
import urllib.request

api_key = os.environ.get("KEDY_API_KEY")
if not api_key:
    raise SystemExit("Set KEDY_API_KEY first.")

payload = {
    "model": "novaq",
    "messages": [{"role": "user", "content": "Hello"}],
}
request = urllib.request.Request(
    "https://api.kedy.dev/v1/chat/completions",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)

try:
    with urllib.request.urlopen(request, timeout=30) as response:
        data = json.load(response)
except urllib.error.HTTPError as error:
    raise SystemExit(f"Kedy API returned HTTP {error.code}.") from None
except (urllib.error.URLError, TimeoutError):
    raise SystemExit("Connection failed or timed out.") from None
except json.JSONDecodeError:
    raise SystemExit("The response was not valid JSON.") from None

try:
    reply = data["choices"][0]["message"]["content"]
except (KeyError, IndexError, TypeError):
    raise SystemExit("The response did not contain a text message.") from None
if not isinstance(reply, str) or not reply.strip():
    raise SystemExit("The response did not contain a text message.")
print(reply)

python3 request.py

py request.py

The request body is encoded as UTF-8. The example checks HTTP errors, connection failures, timeouts, invalid JSON, and responses without a text message.

07Read the response

Check the HTTP status before reading the JSON body. The simplified example below shows the choices[0].message.content path used by the code examples to read text. Additional fields and content in the actual response may vary.

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you?"
      }
    }
  ]
}

• Check that the choices array is not empty.
• Validate that message.content is a string.
• Show a clear error for empty or unexpected responses.
• Render model output as plain text. Sanitize it if you need to render HTML.
• Validate the expected format before using model output in an automated action.

08Troubleshooting

If a request fails, inspect its HTTP status and error message. The table below gives investigation steps for common HTTP statuses; the actual API error body may provide more detail.

Works in the terminal, fails in the application

Check that your server can read the environment variable and that the request body uses the same fields as the cURL example. If the browser calls the Kedy API directly, move that request to your backend. Log the status code while keeping the API key and personal messages out of logs.

09Integrate into your project

Once the example request works, move the same operation into a backend endpoint or server function. Your interface should call only your own server; keep the Kedy API key on the server.

1. Validate input. Reject empty input and choose an appropriate length limit for your application.
2. Read the key on the server. Return a clear configuration error if KEDY_API_KEY is missing.
3. Send the API request. Use a JSON serializer such as JSON.stringify or json.dumps to build the body.
4. Validate the response. Check the HTTP status, JSON format, and text field.
5. Display the result. Handle loading, success, and errors separately. Prevent duplicate submission while a request is in progress.
6. Control usage. Add your own authentication and request limits to a public backend.

Before deployment

• Set the API key in your hosting provider’s server environment variables.
• Do not assume your local .env file is automatically deployed.
• Avoid names or configurations that expose secret environment variables to the frontend.
• Check empty input, missing keys, HTTP errors, and timeouts.
• Verify that production logs do not expose the key.

10FAQ and support

For more help, visit the Kedy contact page. Return to the Çiçekli Teknolig guide for competition videos and participant information.