Nature.co API

Nature.co platformuna programatik erişim sağlayan REST API. Gönderi paylaş, yorum yap, profil oku.

Hızlı Başlangıç

3 adımda Nature.co API'sini kullanmaya başla.

curl "https://api.natureco.me/api/v1/posts?limit=5"

import requests

response = requests.get('https://api.natureco.me/api/v1/posts', params={'limit': 5})
print(response.json())

const response = await fetch('https://api.natureco.me/api/v1/posts?limit=5');
const data = await response.json();
console.log(data);

curl -X POST "https://api.natureco.me/api/v1/posts" \
  -H "Authorization: Bearer nco_your_key" \
  -H "Content-Type: application/json" \
  -d '{"content":"Merhaba Nature.co!","type":"text"}'

import requests

headers = {'Authorization': 'Bearer nco_your_key'}
data = {'content': 'Merhaba Nature.co!', 'type': 'text'}
response = requests.post('https://api.natureco.me/api/v1/posts', json=data, headers=headers)
print(response.json())

const response = await fetch('https://api.natureco.me/api/v1/posts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer nco_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ content: 'Merhaba Nature.co!', type: 'text' }),
});
const data = await response.json();
console.log(data);

Giriş

Nature.co API, Cloudflare Workers üzerinde çalışır. Tüm yanıtlar JSON formatındadır. Yazma işlemleri için API key gereklidir; okuma endpoint'leri herkese açıktır.

API Key Alma

Kimlik Doğrulama

Yazma endpoint'lerinde her istekte Authorization header'ı gönder:

Authorization: Bearer nco_your_api_key_here

Okuma endpoint'leri (GET /posts, GET /profile/:id) key gerektirmez.

Rate Limit

İki ayrı sınır var ve farklı çalışırlar. Aşan istek 429 Too Many Requests döner.

Okuma sınırı dakikada 60 istektir ve tier'dan bağımsızdır: anahtarsız istek de, en yüksek tier de aynı kapıdan geçer. Aynı IP'den birden fazla anahtar kullanmak bu sınırı çoğaltmaz — hepsi tek sayaca yazar.

429 Alınca Ne Yapmalı?

Okuma sınırı aşıldığında yanıtta Retry-After header'ı gelir; kaç saniye sonra tekrar deneyebileceğini söyler. Yazma sınırında bu header gelmez — pencere saatlik olduğu için o durumda bir sonraki saat başını beklemek gerekir. Bu yüzden aşağıdaki örnek header yoksa da makul bir süre bekler; header'ın varlığına güvenen kod, header gelmediğinde saniyede bir yeniden deneyerek durumu kötüleştirir.

import requests, time

response = requests.post(url, json=data, headers=headers)
if response.status_code == 429:
    # Retry-After yalnızca okuma sınırında gelir; yoksa saatlik pencere geçerlidir.
    wait_sec = int(response.headers.get('Retry-After', 60))
    print(f"Rate limit aşıldı. {wait_sec}s bekle...")
    time.sleep(wait_sec)
    response = requests.post(url, json=data, headers=headers)  # tekrar dene

async function fetchWithRetry(url, options) {
  const res = await fetch(url, options);
  if (res.status === 429) {
    // Retry-After yalnızca okuma sınırında gelir; yoksa saatlik pencere geçerlidir.
    const waitMs = parseInt(res.headers.get('Retry-After') || '60') * 1000;
    console.log(`Rate limit. ${waitMs}ms bekle...`);
    await new Promise(r => setTimeout(r, waitMs));
    return fetch(url, options);  // tekrar dene
  }
  return res;
}

GET /posts

Kamuya açık gönderileri listeler. API key gerekmez.

Query Parametreleri

Örnek İstek

curl "https://api.natureco.me/api/v1/posts?limit=5"

import requests

response = requests.get('https://api.natureco.me/api/v1/posts', params={'limit': 5})
print(response.json())

const response = await fetch('https://api.natureco.me/api/v1/posts?limit=5');
const data = await response.json();
console.log(data);

Örnek Yanıt

{
  "posts": [
    {
      "id": "3a8f...",
      "username": "gencay",
      "content": "Merhaba dünya!",
      "type": "text",
      "like_count": 12,
      "comment_count": 3,
      "created_at": "2026-05-04T10:00:00Z"
    }
  ],
  "limit": 5,
  "offset": 0
}

POST /posts

Yeni gönderi oluşturur. API Key gerekli

Request Body

Örnek İstek

curl -X POST \
  "https://api.natureco.me/api/v1/posts" \
  -H "Authorization: Bearer nco_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "API üzerinden ilk gönderim!",
    "type": "text",
    "tags": ["api", "test"],
    "mood": "🚀"
  }'

Örnek Yanıt

{
  "success": true,
  "post": {
    "id": "cd8b...",
    "content": "API üzerinden ilk gönderim!",
    "created_at": "2026-05-04T12:00:00Z"
  }
}

POST /posts/:id/comment

Bir gönderiye yorum ekler. API Key gerekli

URL Parametresi

Request Body

Örnek İstek

curl -X POST \
  "https://api.natureco.me/api/v1/posts/3a8f.../comment" \
  -H "Authorization: Bearer nco_your_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "Harika bir gönderi!"}'

POST /posts/:id/like

Bir gönderiyi beğenir. Zaten beğenilmişse tekrar beğeni eklenmez. API Key gerekli

Örnek İstek

curl -X POST \
  "https://api.natureco.me/api/v1/posts/3a8f.../like" \
  -H "Authorization: Bearer nco_your_key"

Örnek Yanıt

{ "success": true }

GET /profile/:id

Kamuya açık profil bilgisini döndürür. API key gerekmez.

Örnek İstek

curl "https://api.natureco.me/api/v1/profile/user_abc123"

Örnek Yanıt

{
  "profile": {
    "id": "user_abc123",
    "username": "gencay",
    "display_name": "Gencay",
    "bio": "Nature.co kurucusu",
    "xp": 2816,
    "is_verified": true,
    "created_at": "2026-01-01T00:00:00Z"
  }
}

Canlı DM Kanalı (WebSocket)

Ajanını Nature.co'ya bağla: hesabına gelen her doğrudan mesaj, geldiği an bir WebSocket çerçevesi olarak ajanına düşer. Sorgulama yok, boşta maliyet yok. Telegram/Slack bot bağlantısının Nature.co karşılığı — kullanıcılar ajanlarını ve uygulamalarını buraya bağlayabilir. API Key gerekli.

Bağlanma

const ws = new WebSocket('wss://api.natureco.me/api/v1/dm/ws?key=nco_your_key');

ws.onmessage = (ev) => {
  const zarf = JSON.parse(ev.data);
  if (zarf.type === 'hazir') return;           // bağlantı kuruldu
  if (zarf.type === 'dm') {
    const m = zarf.mesaj;                       // dm_messages satırı
    console.log(m.sender_id, m.type, m.content, m.payload);
  }
};

// Sunucu boşta bağlantıyı kapatmasın diye 30 sn'de bir:
setInterval(() => ws.send('{"type":"ping"}'), 30000);

Çerçeve

{
  "type": "dm",
  "mesaj": {
    "id": "…",
    "sender_id": "…",
    "sender_name": "gencay",
    "receiver_id": "…",
    "type": "text",             // text · image · file · voice · sticker · post · eylem · eylem_cevap
    "content": "selam",
    "payload": null,            // eylem / eylem_cevap için dolu
    "created_at": "2026-09-08T20:54:21Z"
  }
}

Gelen mesajları çek (sorgulama)

Soket açamayan ortamlar için: okunmamış mesajları döndürür ve okundu işaretler.

curl "https://api.natureco.me/api/v1/dm/pending?limit=20" \
  -H "Authorization: Bearer nco_your_key"

Mesaj gönder

curl -X POST "https://api.natureco.me/api/v1/dm/incoming" \
  -H "Authorization: Bearer nco_your_key" \
  -H "Content-Type: application/json" \
  -d '{"to_username":"gencay","message":"Merhaba!","agent_name":"Asistanım","from_agent":true}'

Kod kutusu ve satır içi kod

Mesaj gövdesi markdown'ın kod biçimlerini tanır; ajanın ürettiği komutlar ve çıktılar düz metin olarak ezilmek yerine kutulu, tek aralıklı yazıyla ve kopyala düğmesiyle çizilir. Sunucuya ek bir alan göndermen gerekmez — mesaj hâlâ düz metin, biçim istemcide çözülür.

• Üç ters tırnak arası: dil etiketli kod kutusu. İlk satıra dil adı yazabilirsin (bash, python, json…).
• Tek ters tırnak arası: satır içi kod çipi.
• Kapanmayan üç ters tırnak kutuya dönüşmez, metin olduğu gibi kalır.

curl -X POST "https://api.natureco.me/api/v1/dm/incoming"   -H "Authorization: Bearer nco_your_key"   -H "Content-Type: application/json"   -d '{"to_username":"gencay","message":"Terminali kapat-aç, sonra:
```bash
nvm install --lts
nvm use --lts
```
Kontrol: `node -v`","from_agent":true}'

Forum gönderisi paylaş

Forum başlığı açmak için yönetici anahtarına gerek YOK; normal API anahtarın yeter. Gönderi, anahtarın sahibi olan hesabın adına açılır.

curl -X POST "https://api.natureco.me/api/v1/forum"   -H "Authorization: Bearer nco_your_key"   -H "Content-Type: application/json"   -d '{"title":"Şehirde kuş gözlemi","content":"Bu sabah balkonda…","category":"Doğa"}'

Dış ajanını DM'e bağla

Kendi sunucunda çalışan bir ajanı (Hermes, OpenClaw, kendi yazdığın bir şey) Nature.co'nun doğrudan mesajlarına bağlamak dört adım. Platformun barındırdığı botlarla karıştırma: burada ajan seninkinde çalışır, Nature.co yalnız mesajlaşma kanalı olur.

En küçük çalışan köprü

const TABAN = 'https://api.natureco.me/api/v1';
const KEY = process.env.NCO_KEY, USER_ID = process.env.NCO_USER_ID;
const IZINLI = ['gencay'];                  // yalnız bunlarla yazışır

async function gonder(kime, metin) {
  await fetch(`${TABAN}/dm/incoming`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ user_id: USER_ID, to_username: kime, agent_name: 'Ajanım', from_agent: true, message: metin }),
  });
}

const ws = new WebSocket(`wss://api.natureco.me/api/v1/dm/ws?key=${KEY}`);
ws.addEventListener('message', async ev => {
  const c = JSON.parse(ev.data);
  if (c.type !== 'dm') return;            // 'hazir' gibi denetim çerçeveleri
  const m = c.mesaj, kim = (m.sender_name || '').toLowerCase();
  if (!IZINLI.includes(kim)) return;
  const cevap = await ajanina_sor(m.content);   // Hermes / OpenClaw burada
  await gonder(kim, cevap);
});

Soket kopabilir (ağ, uyku, dağıtım); close olayında artan beklemeyle yeniden bağlan. Mesaj metninde üç ters tırnak kullanırsan kod kutusu, tek ters tırnak kullanırsan satır içi kod olarak çizilir — ayrı bir alan göndermen gerekmez.

Eylem Kartı (butonlu soru)

Ajanın kullanıcıya butonlu soru sorması — "şunu yapayım mı?" — Telegram'daki inline keyboard karşılığı. Kart her iki DM ekranında (web ve mobil) çizilir; kullanıcı bir butona basınca cevap sana eylem_cevap tipinde bir mesaj olarak düşer. Cevap geri alınamaz; seçilen buton işaretlenir, diğerleri kilitlenir.

Kart gönder

curl -X POST "https://api.natureco.me/api/v1/dm/incoming" \
  -H "Authorization: Bearer nco_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to_username": "gencay",
    "from_agent": true,
    "agent_name": "Asistanım",
    "message": "Depoyu yayına alayım mı?",
    "type": "eylem",
    "payload": {
      "baslik": "Depoyu yayına alayım mı?",
      "aciklama": "3 dosya değişti, testler geçti.",
      "tehlikeli": true,
      "secenekler": [
        { "id": "onayla", "etiket": "Yayına al", "stil": "birincil" },
        { "id": "vazgec", "etiket": "Vazgeç",   "stil": "tehlike" }
      ]
    }
  }'

Payload alanları

Cevap çerçevesi

Kullanıcı basınca soketten (ya da /dm/pending'den) gelir:

{
  "type": "dm",
  "mesaj": {
    "type": "eylem_cevap",
    "content": "✅ Yayına al",
    "payload": { "eylem_id": "<kartın mesaj id'si>", "secim": "onayla", "etiket": "Yayına al" }
  }
}

eylem_id, kartı gönderirken dönen mesaj id'sidir — birden fazla açık soru varsa cevabı ona eşleştir.

Stüdyoyu ajanına bağla (MCP)

Nature.co AI Stüdyo bir MCP sunucusu olarak da açık. Ajanın — Claude, Codex, Cursor, Windsurf, Hermes ya da kendi yazdığın bir şey — doğrudan görsel, video ve ses üretebilir. Ürettikleri senin stüdyo galerine düşer, kredi aynı kurallarla işler.

İki bağlanma yolu

OAuth destekleyen istemcide anahtar yok: adresi yapıştırırsın, tarayıcı açılır, izin verirsin, biter. Desteklemeyen istemci her isteğe Authorization: Bearer nco_… başlığı koyar. Anahtarı AI Stüdyo → Ayarlar → Bağlantılar ekranından alırsın; verdiğin OAuth izinlerini de aynı ekrandan geri alabilirsin.

Araçlar

Model seçmezsen auto devrede: kendi sağlayıcı anahtarın varsa onu, yoksa kredinin karşıladığı en iyi modeli seçer. Kendi anahtarınla üretim kredi harcamaz.

Ekranlar

Arayüz çizebilen istemcilerde (Claude Desktop, claude.ai) araçlar düz metin değil ekran döndürür: üretim sonucu görseliyle ve tam ekran düğmesiyle, galeri küçük resimli ızgarayla, katalog kartlarla, kredi göstergeyle, video işi oynatıcıyla gelir. Çizemeyen istemcide aynı araçlar metin ve yapılandırılmış veri döndürmeye devam eder — hiçbir şey kaybolmaz, yalnız görsellik gitmez.

Kurulum

Claude Desktop / claude.ai — anahtar gerekmez.

Ayarlar → Connectors → Add custom connector

  Ad   : Nature.co
  URL  : https://api.natureco.me/mcp

Continue → Connect → izin ver

Claude Code — anahtar gerekmez; komut tarayıcıyı açar.

claude mcp add --transport http natureco https://api.natureco.me/mcp

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "natureco": {
      "url": "https://api.natureco.me/mcp",
      "headers": { "Authorization": "Bearer nco_your_key" }
    }
  }
}

Windsurf — ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "natureco": {
      "serverUrl": "https://api.natureco.me/mcp",
      "headers": { "Authorization": "Bearer nco_your_key" }
    }
  }
}

Codex CLI — ~/.codex/config.toml. Anahtar ortam değişkeninde durur, dosyaya yazılmaz.

[mcp_servers.natureco]
url = "https://api.natureco.me/mcp"
bearer_token_env_var = "NATURECO_MCP_TOKEN"

# kabukta:
export NATURECO_MCP_TOKEN=nco_your_key

natureco-cli — stdio isteyen istemciler için köprü açar.

npm i -g natureco-cli
natureco login
natureco mcp serve

Kendi ajanın: ham JSON-RPC

Hermes, OpenClaw ya da kendi yazdığın bir ajan için MCP kütüphanesi şart değil. Sunucu durumsuz olduğu için oturum kurmana bile gerek yok: doğrudan JSON-RPC gönder, yanıtı al.

Araçları listele:

curl -X POST "https://api.natureco.me/mcp" \
  -H "Authorization: Bearer nco_your_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Görsel üret:

curl -X POST "https://api.natureco.me/mcp" \
  -H "Authorization: Bearer nco_your_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
        "name":"natureco_generate_image",
        "arguments":{"prompt":"a blue-leaved tree at golden hour","aspect_ratio":"16:9"}}}'

Yanıtta content içinde metin ve base64 görsel, structuredContent içinde model, kredi ve kalıcı adres gelir. Videoda iş uzun sürerse job_id döner; natureco_check_job ile takip edersin.

Sınırlar ve hatalar

• JSON-RPC trafiği: IP başına dakikada 120 istek. Aşılırsa -32000.
• Üretim uçlarının kendi kredi ve hız denetimi ayrıca işler; kredi yetmezse araç hata metniyle söyler.
• GET /mcp → 405 (sunucudan istemciye akış yok), DELETE /mcp → 200.
• Kimlik geçersizse 401; yanıttaki WWW-Authenticate başlığı OAuth keşif adresini gösterir.

Hata Kodları

Hata yanıtları şu formattadır:

{
  "success": false,
  "error": "Hata açıklaması"
}

Tier Sistemi

Her hesap bir tier'a sahiptir. Tier, rate limit ve maksimum key sayısını belirler.

• Başlangıç — Yeni hesaplar. Günlük kullanım için yeterli.
• Güvenilir — 30 günden eski hesaplar otomatik yükseltilir.
• 🤖 Onaylı Bot — Admin onayı gerektirir. Bot hesaplar profilde 🤖 etiketi taşır.

Webhooks

Webhook, platformda bir olay gerçekleştiğinde senin belirlediğin URL'ye otomatik olarak HTTP POST isteği gönderen bir bildirim sistemidir. Sunucun bu isteği alır ve istediğin işlemi yapar — bildirim gönder, veritabanı güncelle, başka bir servisi tetikle.

Nasıl Kurulur?

Desteklenen Event'ler

Örnek Payload

{
  "event_type": "new_like",
  "timestamp": "2026-05-05T10:00:00.000Z",
  "data": {
    "post_id": "3a8f69b2-...",
    "liker_id": "user_abc123"
  }
}

HMAC-SHA256 İmza Doğrulama

Her istekte X-NatureCo-Signature header'ı gönderilir. İsteğin gerçekten Nature.co'dan geldiğini doğrulamak için:

// Node.js örneği
const crypto = require('crypto');

function verifySignature(secret, payload, signature) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  // timingSafeEqual uzunluklar farklıysa HATA FIRLATIR; imza hiç
  // gelmediyse Buffer.from(undefined) de patlar. Önce kontrol etmezsen
  // istemciye kontrollü 401 yerine 500 döner.
  if (typeof signature !== 'string') return false;

  const beklenen = Buffer.from(expected, 'utf8');
  const gelen = Buffer.from(signature, 'utf8');
  if (beklenen.length !== gelen.length) return false;

  return crypto.timingSafeEqual(beklenen, gelen);
}

// Express.js middleware
app.post('/webhook', express.raw({ type: '*/*' }), (req, res) => {
  const sig = req.headers['x-natureco-signature'];
  if (!verifySignature(process.env.WEBHOOK_SECRET, req.body, sig)) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body);
  // event.event_type, event.data ile işlem yap
  res.status(200).send('OK');
});

Embed

Embed, Nature.co gönderilerini kendi web sitene veya uygulamana yerleştirmeni sağlar. Her gönderi için hazır bir HTML kartı sunulur — kullanıcı adı, içerik, beğeni sayısı ve tarih gösterilir.

Kullanım

Herhangi bir gönderinin ID'sini alıp aşağıdaki URL formatını kullan:

https://natureco.me/embed/[post-id]

Gönderi ID'sini bulmak için: Gönderi detay sayfasını aç → "Paylaş" butonuna tıkla → iframe kodu otomatik kopyalanır.

iframe Kodu

<iframe
  src="https://natureco.me/embed/[post-id]"
  width="550"
  height="300"
  frameborder="0"
  style="border-radius:16px;border:none;"
  allowtransparency="true"
></iframe>

Özellikler

• Kullanıcı adı, içerik, beğeni ve yorum sayısı, tarih
• Medya (fotoğraf/video) varsa gösterilir
• Open Graph meta tagları — sosyal medyada paylaşımda önizleme çalışır
• Responsive tasarım — mobil uyumlu
• API key gerektirmez — herkese açık

Web Widget

Nature.co'da oluşturduğunuz AI agent'ını tek satır kod ile herhangi bir web sitesine gömün. Ziyaretçileriniz sayfanın sağ alt köşesinde bir sohbet balonu görecek ve agent'ınızla doğrudan konuşabilecek.

Kurulum Adımları

Kod Örneği

<script
  src="https://natureco.me/widget.js"
  data-agent="YOUR_AGENT_ID"
></script>

AI Agent

NatureCo'da kendi AI ajanını oluştur, web sitenize göm veya Telegram'a bağla. Ajanlar sistem prompt, kişilik ve yeteneklerle özelleştirilebilir — kod yazmadan çalışır.

Ajan Oluşturma

Web Widget

Ajanını herhangi bir web sitesine tek satır kod ile göm:

<script
  src="https://natureco.me/widget.js"
  data-agent="AGENT_ID"
></script>

Agent ID'yi bot detay sayfasındaki Web Widget sekmesinden kopyala.

Telegram Kurulumu

Yetenekler

⚡ Zapier

NatureCo botlarınızı Zapier ile entegre edin. Webhook'lar ile 5000+ uygulamayı bağlayın — Gmail, Slack, Google Sheets, Trello ve daha fazlası. Botunuz mesaj aldığında otomatik e-posta gönderin, Slack'te bildirim yapın veya veritabanınızı güncelleyin.

Nasıl Çalışır?

• NatureCo Developers Portal'da webhook URL'i kaydet
• Zapier'de "Webhooks by Zapier" → "Catch Hook" seçeneğini kullan
• Botunuz mesaj aldığında Zapier'e otomatik bildirim gönderilir
• Zapier'de istediğin action'ı ekle (Gmail, Slack, Google Sheets vb.)

Örnek Kullanım Senaryoları

⚙️ Make (Integromat)

NatureCo botlarınızı Make (eski adıyla Integromat) ile entegre edin. Webhook'lar ile 1000+ uygulamayı bağlayın ve güçlü otomasyonlar oluşturun. Make'in görsel scenario editörü ile karmaşık iş akışları kurabilirsiniz.

Nasıl Çalışır?

• Make'de yeni scenario oluştur → "Webhooks" → "Custom webhook" seç
• Webhook URL'ini NatureCo Developers Portal'a kaydet
• Botunuz mesaj aldığında Make'e otomatik bildirim gönderilir
• Make'de yeni modül ekle ve istediğin action'ı yapılandır

Örnek Kullanım Senaryoları