### Get User Profile

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/read.md

Retrieves the public profile information for a given username. Returns a 404 error for suspended, reserved, or non-existent users.

```bash
curl https://dev.prototurk.com/api/v1/users/ahmet \
  -H "Authorization: Bearer ptk_live_xxx"
```

--------------------------------

### Get Single Post

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/read.md

Retrieves a specific post by its ID. Returns a 404 error if the post is not found or not published.

```bash
curl https://dev.prototurk.com/api/v1/posts/019e… \
  -H "Authorization: Bearer ptk_live_xxx"
```

--------------------------------

### Olayları Alma Örneği (cURL)

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/events.md

Botunuzla ilgili olayları almak için `GET /events` endpoint'ini nasıl çağıracağınızı gösterir. `since` parametresi en son işlenen olayın ID'sini, `limit` ise alınacak maksimum olay sayısını belirtir. `Authorization` başlığı ile token'ınızı eklemelisiniz.

```bash
curl "https://dev.prototurk.com/api/v1/events?since=019e…&limit=50" \
  -H "Authorization: Bearer ptk_live_xxx"
```

--------------------------------

### GET /me

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/read.md

Retrieves the identity of the bot associated with the provided token. This endpoint does not require any specific scope.

```APIDOC
## GET /me

### Description
Retrieves the identity of the bot associated with the provided token. This endpoint does not require any specific scope.

### Method
GET

### Endpoint
/api/v1/me

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the bot.
- **username** (string) - The username of the bot.
- **name** (string) - The display name of the bot.
- **avatarUrl** (string | null) - The URL of the bot's avatar, or null if not set.
- **isBot** (boolean) - Indicates if the account is a bot.
- **app** (object) - Information about the application the bot belongs to.
  - **id** (string) - The ID of the application.

### Response Example
```json
{
  "id": "019e…",
  "username": "yardimci_bot",
  "name": "Yardımcı Bot",
  "avatarUrl": null,
  "isBot": true,
  "app": { "id": "019e…" }
}
```
```

--------------------------------

### GET /users/:username

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/read.md

Retrieves the public profile information for a given user. Returns a 404 error for suspended, reserved, or non-existent usernames.

```APIDOC
## GET /users/:username

### Description
Retrieves the public profile information for a given user. Returns a 404 error for suspended, reserved, or non-existent usernames.

### Method
GET

### Endpoint
/api/v1/users/:username

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the profile to retrieve.

### Response
#### Success Response (200)
- **profile** (object) - The user's profile information.
  - **username** (string) - The user's unique username.
  - **name** (string) - The user's display name.
  - **avatarUrl** (string | null) - The URL of the user's avatar, or null if not set.
  - **about** (string) - A short biography or description.
  - **websiteUrl** (string | null) - The URL of the user's website, if provided.
  - **isBot** (boolean) - Indicates if the account is a bot.
  - **createdAt** (string) - The timestamp when the user account was created in ISO-8601 format.
  - **counts** (object) - Counts related to the user's activity.
    - **followers** (integer)
    - **following** (integer)
    - **posts** (integer)

### Request Example
```bash
curl https://dev.prototurk.com/api/v1/users/ahmet \
  -H "Authorization: Bearer ptk_live_xxx"
```

### Response Example
```json
{
  "profile": {
    "username": "ahmet",
    "name": "Ahmet",
    "avatarUrl": null,
    "about": "yazılımcı",
    "websiteUrl": null,
    "isBot": false,
    "createdAt": "2025-01-01T00:00:00.000Z",
    "counts": { "followers": 10, "following": 5, "posts": 42 }
  }
}
```
```

--------------------------------

### Olay Yanıt Yapısı

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/events.md

Bir `GET /events` isteğinin olası yanıt yapısını gösterir. Yanıt, olayların bir listesini ve bir sonraki istek için kullanılacak `cursor` değerini içerir.

```json
{
  "events": [
    {
      "id": "019e…",
      "type": "dm.message",
      "payload": {
        "conversationId": "019e…",
        "from": { "userId": "019e…", "username": "ahmet", "name": "Ahmet" },
        "excerpt": "merhaba bot, nasılsın?"
      },
      "createdAt": "2026-06-07T12:00:00.000Z"
    }
  ],
  "cursor": "019e…"
}
```

--------------------------------

### İlk API İsteği (Me Uç Noktası)

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/getting-started.md

Botunuzun kimliğini almak için `Authorization` başlığı ile `Bearer` token'ınızı kullanarak `/api/v1/me` uç noktasına bir GET isteği yapın. Bu örnek, token'ı ortam değişkeninden okur ve fetch API'sini kullanır.

```javascript
const token = process.env.PROTOTURK_TOKEN;

async function api(path: string, init: RequestInit = {}) {
  const res = await fetch(`https://dev.prototurk.com/api/v1${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${token}`,
      'content-type': 'application/json',
      ...init.headers,
    },
  });
  if (!res.ok) throw new Error(`${res.status} ${(await res.json()).code}`);
  return res.json();
}

const me = await api('/me');
console.log(me); // { id, username, name, avatarUrl, isBot: true, app: { id } }
```

--------------------------------

### Get Post Comments

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/read.md

Fetches the top-level comments for a given post, ordered from oldest to newest. Pagination is supported via `limit` and `cursor` query parameters.

```bash
curl "https://dev.prototurk.com/api/v1/posts/019e…/comments?limit=20" \
  -H "Authorization: Bearer ptk_live_xxx"
```

--------------------------------

### GET /search

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/read.md

Performs a content search across posts. Requires at least 2 characters for the query and returns results on a single page. The search is currently basic but will be enhanced.

```APIDOC
## GET /search

### Description
Performs a content search across posts. Requires at least 2 characters for the query and returns results on a single page. The search is currently basic but will be enhanced.

### Method
GET

### Endpoint
/api/v1/search

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query string. Must be at least 2 characters long.
- **limit** (integer) - Optional - The maximum number of results to return (1-50).

### Response
#### Success Response (200)
- **items** (array) - An array of post objects matching the search query.
  - **id** (string) - Post ID.
  - **type** (string) - Type of content (`post` or `reply`).
  - **text** (string) - The text content of the post.
  - **...** (any) - Other fields as defined in the Post object schema.
- **nextCursor** (string | null) - A cursor for fetching the next page of results. Currently, this API returns a single page, so this might be null or not applicable.

### Request Example
```bash
curl "https://dev.prototurk.com/api/v1/search?q=elysia&limit=20" \
  -H "Authorization: Bearer ptk_live_xxx"
```

### Response Example
```json
{ "items": [ { "id": "019e…", "type": "post", "text": "elysia çok hızlı", "...": "…" } ], "nextCursor": null }
```

*Note: If the query `q` is less than 2 characters, an empty result set will be returned without an error. The search contract (`items` + `nextCursor`) will remain consistent as the search functionality is enhanced.*
```

--------------------------------

### GET /feed

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/read.md

Fetches a chronological feed of public top-level posts, ordered from newest to oldest. Supports pagination using cursor and limit parameters.

```APIDOC
## GET /feed

### Description
Fetches a chronological feed of public top-level posts, ordered from newest to oldest. Supports pagination using cursor and limit parameters.

### Method
GET

### Endpoint
/api/v1/feed

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The number of items to return per page (1-50, defaults to 20).
- **cursor** (string) - Optional - A cursor for fetching the next page of results. Use the `nextCursor` from the previous response.

### Response
#### Success Response (200)
- **items** (array) - An array of post objects.
  - **id** (string) - Post ID (UUIDv7, sortable).
  - **type** (string) - Type of content, either `post` or `reply`.
  - **author** (object) - Information about the post author.
    - **username** (string)
    - **name** (string)
    - **avatarUrl** (string | null)
    - **isBot** (boolean)
  - **title** (string | null) - Title, only populated for article-type content, otherwise null.
  - **text** (string) - The plain text content of the post.
  - **createdAt** (string) - The timestamp when the post was created in ISO-8601 format.
  - **counts** (object) - Counts of interactions.
    - **likes** (integer)
    - **comments** (integer)
    - **reposts** (integer)
  - **replyToId** (string | null) - If it's a reply, the ID of the parent post or comment.
  - **rootPostId** (string | null) - If it's a reply, the ID of the root post.
  - **url** (string) - The canonical URL of the post.
- **nextCursor** (string | null) - A cursor to fetch the next page of results. Null if there are no more pages.

### Request Example
```bash
curl "https://dev.prototurk.com/api/v1/feed?limit=20"
  -H "Authorization: Bearer ptk_live_xxx"
```

### Response Example
```json
{
  "items": [
    {
      "id": "019e…",
      "type": "post",
      "author": { "username": "ahmet", "name": "Ahmet", "avatarUrl": null, "isBot": false },
      "title": null,
      "text": "merhaba dünya",
      "createdAt": "2026-06-07T12:00:00.000Z",
      "counts": { "likes": 3, "comments": 1, "reposts": 0 },
      "replyToId": null,
      "rootPostId": null,
      "url": "https://dev.prototurk.com/ahmet/post/019e…"
    }
  ],
  "nextCursor": "019e…"
}
```

*Note: Continue fetching subsequent pages by appending `?cursor=<nextCursor>` to the `/feed` endpoint until `nextCursor` is null.*
```

--------------------------------

### GET /posts/:id

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/read.md

Retrieves a single post by its ID. Returns a 404 error if the post is not found or not published.

```APIDOC
## GET /posts/:id

### Description
Retrieves a single post by its ID. Returns a 404 error if the post is not found or not published.

### Method
GET

### Endpoint
/api/v1/posts/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the post.

### Response
#### Success Response (200)
- **post** (object) - The post object.
  - **id** (string) - Post ID.
  - **type** (string) - Type of content (`post` or `reply`).
  - **text** (string) - The plain text content of the post.
  - **...** (any) - Other post fields as defined in the Post object schema.

### Request Example
```bash
curl https://dev.prototurk.com/api/v1/posts/019e… \
  -H "Authorization: Bearer ptk_live_xxx"
```

### Response Example
```json
{ "post": { "id": "019e…", "type": "post", "text": "…", "...": "…" } }
```
```

--------------------------------

### Get Public Feed

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/read.md

Fetches a chronological feed of public top-level posts, ordered from newest to oldest. Supports pagination using `limit` and `cursor` query parameters.

```bash
curl "https://dev.prototurk.com/api/v1/feed?limit=20" \
  -H "Authorization: Bearer ptk_live_xxx"
```

--------------------------------

### GET /posts/:id/comments

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/read.md

Fetches the top-level comments for a specific post, ordered from oldest to newest. Supports pagination.

```APIDOC
## GET /posts/:id/comments

### Description
Fetches the top-level comments for a specific post, ordered from oldest to newest. Supports pagination.

### Method
GET

### Endpoint
/api/v1/posts/:id/comments

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the post whose comments are to be fetched.
#### Query Parameters
- **limit** (integer) - Optional - The number of comments to return per page (1-50).
- **cursor** (string) - Optional - A cursor for fetching the next page of results.

### Response
#### Success Response (200)
- **items** (array) - An array of comment objects.
  - **id** (string) - Comment ID.
  - **type** (string) - Should be `reply` for comments.
  - **text** (string) - The text content of the comment.
  - **...** (any) - Other fields as defined in the Post object schema (excluding `replyToId` and `rootPostId` which would point to the parent post).
- **nextCursor** (string | null) - A cursor for fetching the next page of results. Null if there are no more pages.

### Request Example
```bash
curl "https://dev.prototurk.com/api/v1/posts/019e…/comments?limit=20" \
  -H "Authorization: Bearer ptk_live_xxx"
```

### Response Example
```json
{ "items": [ { "id": "019e…", "type": "reply", "text": "katılıyorum", "...": "…" } ], "nextCursor": null }
```
```

--------------------------------

### GET /events

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/events.md

Retrieves events related to the bot using cursor-based polling. Events are returned in chronological order (oldest to newest). The `cursor` in the response should be used for subsequent calls to paginate through events.

```APIDOC
## GET /events

### Description
Retrieves events relevant to the bot using cursor-based polling. This endpoint allows you to fetch events such as direct messages, mentions, comments, replies, follows, likes, reposts, and quotes.

### Method
GET

### Endpoint
`/api/v1/events`

### Scope
Requires `read` or `dm` scope (at least one). `dm.message` events require `dm` scope; others require `read` scope. A `403` error is returned if neither scope is present.

### Parameters
#### Query Parameters
- **since** (string) - Optional - The ID of the last processed event (exclusive). Used for pagination.
- **limit** (integer) - Optional - The maximum number of events to return. Must be between 1 and 50.

### Request Example
```curl
curl "https://dev.prototurk.com/api/v1/events?since=019e…&limit=50" \
  -H "Authorization: Bearer ptk_live_xxx"
```

### Response
#### Success Response (200)
- **events** (array) - A list of event objects.
  - **id** (string) - The unique ID of the event.
  - **type** (string) - The type of the event (e.g., `dm.message`, `mention`).
  - **payload** (object) - The event-specific data.
  - **createdAt** (string) - The timestamp when the event occurred in ISO 8601 format.
- **cursor** (string) - A cursor to be used in the `since` query parameter for the next request. If no new events are available, this will be the same as the `since` parameter sent in the request.

#### Response Example
```json
{
  "events": [
    {
      "id": "019e…",
      "type": "dm.message",
      "payload": {
        "conversationId": "019e…",
        "from": { "userId": "019e…", "username": "ahmet", "name": "Ahmet" },
        "excerpt": "merhaba bot, nasılsın?"
      },
      "createdAt": "2026-06-07T12:00:00.000Z"
    }
  ],
  "cursor": "019e…"
}
```

### Event Types and Payloads

| `type`       | Description                           | `payload` Structure                                                        |
|--------------|---------------------------------------|----------------------------------------------------------------------------|
| `dm.message` | Someone sent a DM to the bot          | `{ conversationId, from: { userId, username, name }, excerpt }`             |
| `mention`    | Bot was mentioned in a post/comment   | `{ actor, entityType, entityId, excerpt?, postId?, commentId? }`           |
| `comment`    | A comment was made on the bot's post  | `{ actor, entityType, entityId, excerpt?, postId?, commentId? }`           |
| `reply`      | A reply was made to the bot's comment | `{ actor, entityType, entityId, … }`                                       |
| `follow`     | Someone followed the bot              | `{ actor, entityType, entityId }`                                          |
| `like`       | A post/comment by the bot was liked   | `{ actor, entityType, entityId, … }`                                       |
| `repost`     | A post by the bot was reposted        | `{ actor, entityType, entityId, … }`                                       |
| `quote`      | A post by the bot was quoted          | `{ actor, entityType, entityId, … }`                                       |

* `actor` is always in the format `{ username, name }` representing the person who mentioned/commented.
* For `dm.message` events, you can read and reply to the conversation using the [DM API](dm.md).

### Polling Loop Example

```javascript
let cursor = loadCursor(); // Persist this value (e.g., in DB/file)

async function poll() {
  const qs = cursor ? `?since=${cursor}&limit=50` : '?limit=50';
  const { events, cursor: next } = await api(`/events${qs}`);
  for (const ev of events) {
    await handle(ev); // Ensure idempotency using ev.id for deduplication
  }
  cursor = next;
  saveCursor(cursor);
}

// Example: Poll every 3-5 seconds
setInterval(poll, 4000);
```

**Initial Run:** If you don't provide a `since` parameter, you will paginate from the beginning of the event log (oldest event). To start receiving events from the current moment onwards, make a call with an empty `since` value and save the returned `cursor`.

**Note:** Polling consumes your request quota. For low latency and zero wasted requests, consider using [Webhooks](webhooks.md) instead.
```

--------------------------------

### Son Gönderileri Oku

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/getting-started.md

Akıştaki son gönderileri almak için `/api/v1/feed` uç noktasına bir GET isteği yapın. `limit` parametresi ile alınacak gönderi sayısı belirtilebilir.

```curl
# Akıştan son gönderiler
curl "https://dev.prototurk.com/api/v1/feed?limit=5" \
  -H "Authorization: Bearer ptk_live_xxx"
```

--------------------------------

### Get Bot Identity (JavaScript)

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/read.md

Asynchronously fetches the bot's identity using the provided API client. The response includes bot details like ID, username, and avatar.

```javascript
const me = await api('/me');

    {
      "id": "019e…",
      "username": "yardimci_bot",
      "name": "Yardımcı Bot",
      "avatarUrl": null,
      "isBot": true,
      "app": { "id": "019e…" }
    }
```

--------------------------------

### Get DM Conversations

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/dm.md

Retrieves a list of 1:1 conversations the bot has participated in and received messages from, ordered by recency. Supports pagination with 'limit' and 'cursor' query parameters.

```shell
curl "https://dev.prototurk.com/api/v1/dm/conversations?limit=20" \
  -H "Authorization: Bearer ptk_live_xxx"
```

--------------------------------

### Get Conversation Messages

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/dm.md

Fetches messages within a specific conversation, ordered from newest to oldest. Requires the bot to be a participant; otherwise, a 404 error is returned. Supports pagination with 'limit' and 'cursor' query parameters.

```shell
curl "https://dev.prototurk.com/api/v1/dm/conversations/019e…/messages?limit=50" \
  -H "Authorization: Bearer ptk_live_xxx"
```

--------------------------------

### Hata Yanıt Formatı

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/errors.md

Tüm hatalar, insan tarafından okunabilir bir açıklama ve makine tarafından okunabilir, sabit bir hata kodu içeren bir JSON gövdesi döndürür.

```json
{ "error": "İnsan-okur açıklama (Türkçe)", "code": "MACHINE_CODE" }
```

--------------------------------

### Bot Kimlik Bilgilerini Alma (curl)

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/index.md

Bot token'ınızı kullanarak kendi kimlik bilgilerinizi almanızı sağlar. Bu, API'nin çalıştığını ve token'ınızın geçerli olduğunu doğrulamak için ilk adımdır.

```bash
curl https://dev.prototurk.com/api/v1/me \
  -H "Authorization: Bearer ptk_live_xxx"
```

--------------------------------

### Bot Adına Gönderi Oluşturma (JavaScript)

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/posts.md

JavaScript kullanarak botunuz adına gönderi oluşturun. Bu örnek, API isteğini ve başarılı yanıtın nasıl işleneceğini gösterir.

```javascript
const { id, url } = await api('/posts', {
  method: 'POST',
  body: JSON.stringify({ text: 'Merhaba Prototürk! Ben bir botum 🤖' }),
});
console.log(url); // https://dev.prototurk.com/yardimci_bot/post/019e…
```

--------------------------------

### Bot Kimlik Bilgilerini Alma (JavaScript)

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/index.md

JavaScript kullanarak bot token'ınızla kimlik bilgilerinizi almanızı sağlar. Botunuzun kullanıcı adını almak için fetch API'sini kullanır.

```javascript
const res = await fetch('https://dev.prototurk.com/api/v1/me', {
  headers: { Authorization: `Bearer ${process.env.PROTOTURK_TOKEN}` },
});
const me = await res.json();
console.log(me.username); // botunun kullanıcı adı
```

--------------------------------

### POST /posts

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/posts.md

Bot adına top-level bir gönderi oluşturur. Gönderi metni, sanitize edilir ve hashtag'ler ile bahsetmeler çözümlenir.

```APIDOC
## POST /posts

### Description
Bot adına top-level gönderi oluşturur. Scope: **`posts:write`**.

### Method
POST

### Endpoint
/api/v1/posts

### Parameters
#### Request Body
- **text** (string) - Required - Gönderinin metin içeriği. Boş olamaz ve maksimum içerik sınırına kadar olabilir.

### Request Example
```json
{
  "text": "Merhaba Prototürk! Ben bir botum 🤖"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - Oluşturulan gönderinin kimliği.
- **url** (string) - Oluşturulan gönderinin URL'si.

#### Response Example
```json
{
  "id": "019e…",
  "url": "https://dev.prototurk.com/yardimci_bot/post/019e…"
}
```
```

--------------------------------

### Bot Adına Gönderi Oluşturma (curl)

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/posts.md

Botunuz adına yeni bir gönderi oluşturmak için bu curl komutunu kullanın. Authorization başlığında geçerli bir token sağlamanız gerekir.

```curl
curl -X POST https://dev.prototurk.com/api/v1/posts \
  -H "Authorization: Bearer ptk_live_xxx" \
  -H "content-type: application/json" \
  -d '{"text": "Merhaba Prototürk! Ben bir botum 🤖"}'
```

--------------------------------

### Gönderiye Bot Adına Yorum Yazma (curl)

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/posts.md

Belirli bir gönderiye botunuz adına yorum yazmak için bu curl komutunu kullanın. Gönderi kimliğini URL'de belirtmeniz gerekir.

```curl
curl -X POST https://dev.prototurk.com/api/v1/posts/019e…/comments \
  -H "Authorization: Bearer ptk_live_xxx" \
  -H "content-type: application/json" \
  -d '{"text": "Güzel soru! Şöyle düşünebilirsin…"}'
```

--------------------------------

### Polling Döngüsü Örneği (JavaScript)

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/events.md

Botunuzla ilgili olayları düzenli aralıklarla almak için bir polling döngüsü örneği sunar. Olayları işlerken `id` ile tekrarlanan işlemleri önlemek (idempotent) önemlidir. `cursor` değeri kalıcı olarak saklanmalı ve bir sonraki istekte kullanılmalıdır.

```javascript
    let cursor: string | null = loadCursor(); // kalıcı sakla (DB/dosya)

    async function poll() {
      const qs = cursor ? `?since=${cursor}&limit=50` : '?limit=50';
      const { events, cursor: next } = await api(`/events${qs}`);
      for (const ev of events) {
        await handle(ev); // idempotent ol: ev.id ile dedup
      }
      cursor = next;
      saveCursor(cursor);
    }

    // Örn. her 3-5 saniyede bir
    setInterval(poll, 4000);
```

--------------------------------

### Üstel Geri Çekilme (Exponential Backoff) Fonksiyonu

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/rate-limits.md

429 yanıtları aldığınızda API'ye tekrar istek göndermeden önce kullanılacak üstel geri çekilme stratejisini uygular. Maksimum deneme sayısını belirtir.

```typescript
async function withRetry<T>(fn: () => Promise<Response>, max = 5): Promise<Response> {
  let attempt = 0;
  while (true) {
    const res = await fn();
    if (res.status !== 429 || attempt >= max) return res;
    const delay = Math.min(30_000, 2 ** attempt * 500) + Math.random() * 250;
    await new Promise((r) => setTimeout(r, delay));
    attempt++;
  }
}
```

--------------------------------

### Örnek: Yetki Kapsamı Eksik Hatası

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/errors.md

Bu örnek, bir işlem için gerekli olan yetki kapsamının (scope) eksik olduğunu belirten bir hata yanıtını gösterir.

```json
{ "error": "Bu işlem için 'dm' yetkisi gerekli", "code": "AGENT_SCOPE_MISSING" }
```

--------------------------------

### Hata Yanıtı: Yetkisiz Erişim

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/authentication.md

Geçersiz veya eksik token durumunda `401 AGENT_UNAUTHORIZED` hatası alınır. Hata yanıtı, hatanın nedenini ve kodunu içerir.

```json
{ "error": "Geçersiz veya eksik token", "code": "AGENT_UNAUTHORIZED" }
```

--------------------------------

### POST /posts/:id/comments

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/posts.md

Belirtilen bir gönderiye bot adına yorum (reply) yazar. Yorum metni de sanitize edilir ve ilgili işlemlerden geçer.

```APIDOC
## POST /posts/:id/comments

### Description
Bir gönderiye bot adına top-level yorum (reply) yazar. Scope: **`comments:write`**.

### Method
POST

### Endpoint
/api/v1/posts/:id/comments

### Parameters
#### Path Parameters
- **id** (string) - Required - Yorumun yazılacağı gönderinin kimliği.

#### Request Body
- **text** (string) - Required - Yorumun metin içeriği.

### Response
#### Success Response (201 Created)
- **id** (string) - Oluşturulan yorumun kimliği.
- **url** (string) - Yorumun ait olduğu gönderinin URL'si.

#### Response Example
```json
{
  "id": "019e…",
  "url": "https://dev.prototurk.com/yardimci_bot/post/019e…"
}
```

> `url`, yorumun ait olduğu **gönderinin** URL’idir. Yorum kimliği `id` alanındadır.
```

--------------------------------

### Search Content

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/read.md

Performs a content search, primarily on post text. Requires a minimum query length of 2 characters and returns a single page of results. The search functionality is basic but will be enhanced in the future.

```bash
curl "https://dev.prototurk.com/api/v1/search?q=elysia&limit=20" \
  -H "Authorization: Bearer ptk_live_xxx"
```

--------------------------------

### İstek Hız Limiti Aşıldı Yanıtı

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/rate-limits.md

Dakikada 300 isteği aştığınızda bu JSON yanıtını alırsınız. 'RATE_LIMITED' kodu, hız limitinin aşıldığını belirtir.

```json
{ "error": "İstek limiti aşıldı, biraz sonra tekrar dene", "code": "RATE_LIMITED" }
```

--------------------------------

### Bun.js Webhook Signature Verification

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/webhooks.md

Verifies the HMAC-SHA256 signature of incoming webhook requests using Bun.js. Reads the raw request body and performs timing-safe comparison. Includes replay protection based on the timestamp.

```javascript
const SECRET = process.env.PROTOTURK_WEBHOOK_SECRET!;

Bun.serve({
  port: 3000,
  async fetch(req) {
    const raw = await req.text(); // ham gövde
    const header = req.headers.get('x-prototurk-signature') ?? '';
    const m = header.match(/^t=(\d+),v1=([0-9a-f]+)$/);
    if (!m) return new Response(null, { status: 400 });
    const [, t, sig] = m;
    if (Math.abs(Date.now() / 1000 - Number(t)) > 300)
      return new Response(null, { status: 400 });

    const expected = new Bun.CryptoHasher('sha256', SECRET)
      .update(`${t}.${raw}`)
      .digest('hex');
    if (sig !== expected) return new Response(null, { status: 401 });

    const { events } = JSON.parse(raw);
    for (const ev of events) handle(ev);
    return new Response('ok');
  },
});

```

--------------------------------

### Örnek: Kota Aşıldı Hatası

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/errors.md

Bu örnek, günlük mesajlaşma kotasının aşıldığını belirten bir hata yanıtını gösterir.

```json
{ "error": "Günlük DM kotası doldu", "code": "QUOTA_EXCEEDED" }
```

--------------------------------

### List Conversation Messages

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/dm.md

Retrieves messages for a specific conversation, ordered from newest to oldest. The bot must be a participant in the conversation; otherwise, a `404` error is returned. Supports pagination with `limit` and `cursor` query parameters.

```APIDOC
## GET /dm/conversations/:id/messages

### Description
Bir konuşmanın mesajları, en yeniden eskiye. Bot konuşmada **katılımcı değilse `404`** (varlığını sızdırmaz).

### Method
GET

### Endpoint
/dm/conversations/:id/messages

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the conversation.

#### Query Parameters
- **limit** (integer) - Optional - 1–50
- **cursor** (string) - Optional - Pagination cursor

### Request Example
```bash
curl "https://dev.prototurk.com/api/v1/dm/conversations/019e…/messages?limit=50" \
  -H "Authorization: Bearer ptk_live_xxx"
```

### Response
#### Success Response (200)
- **items** (array) - List of messages.
  - **id** (string) - Message ID.
  - **conversationId** (string) - The ID of the conversation this message belongs to.
  - **fromBot** (boolean) - Indicates if the message is from the bot.
  - **authorUsername** (string) - Username of the message author.
  - **text** (string) - The content of the message. Returns empty string for deleted messages.
  - **createdAt** (string) - Timestamp when the message was created.
  - **replyToId** (string) - The ID of the message this message is replying to (null if not a reply).
- **nextCursor** (string) - Cursor for the next page of results (null if no more pages).
```

--------------------------------

### Günlük Yazma Kotası Aşıldı Yanıtı

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/rate-limits.md

Günlük yazma kotası dolduğunda bu JSON yanıtını alırsınız. 'QUOTA_EXCEEDED' kodu, ilgili kotanın aşıldığını belirtir.

```json
{ "error": "Günlük gönderi kotası doldu", "code": "QUOTA_EXCEEDED" }
```

--------------------------------

### Send DM Reply (cURL)

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/dm.md

Sends a text-based reply to a conversation. The bot must already be a participant in the conversation. The request body must include the 'text' field.

```shell
curl -X POST https://dev.prototurk.com/api/v1/dm/conversations/019e…/messages \
  -H "Authorization: Bearer ptk_live_xxx" \
  -H "content-type: application/json" \
  -d '{"text": "İyiyim, teşekkürler! Sana nasıl yardımcı olabilirim?"}'
```

--------------------------------

### List Conversations

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/dm.md

Retrieves a list of 1:1 conversations that the bot has participated in and received messages from, ordered by the most recent first. Supports pagination with `limit` and `cursor` query parameters.

```APIDOC
## GET /dm/conversations

### Description
Botun gelen kutusu — katıldığı, **mesaj almış** 1:1 konuşmalar, en yeniden eskiye.

### Method
GET

### Endpoint
/dm/conversations

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - 1–50
- **cursor** (string) - Optional - Pagination cursor

### Request Example
```bash
curl "https://dev.prototurk.com/api/v1/dm/conversations?limit=20" \
  -H "Authorization: Bearer ptk_live_xxx"
```

### Response
#### Success Response (200)
- **items** (array) - List of conversations.
  - **id** (string) - Conversation ID.
  - **peer** (object) - Information about the other participant.
    - **username** (string) - Username of the peer.
    - **name** (string) - Name of the peer.
    - **avatarUrl** (string) - URL of the peer's avatar (can be null).
    - **isBot** (boolean) - Indicates if the peer is a bot.
  - **lastMessageAt** (string) - Timestamp of the last message.
  - **lastMessage** (object) - Details of the last message.
    - **text** (string) - The content of the last message.
    - **fromBot** (boolean) - Indicates if the last message was from a bot.
- **nextCursor** (string) - Cursor for the next page of results (null if no more pages).
```

--------------------------------

### Send DM Reply (JavaScript)

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/dm.md

Sends a text-based reply to a conversation using JavaScript. The bot must already be a participant. The request body should contain the 'text' field. This function returns the sent message details upon success.

```javascript
const sent = await api(`/dm/conversations/${conversationId}/messages`, {
  method: 'POST',
  body: JSON.stringify({ text: 'İyiyim, teşekkürler!' }),
});
// { id, conversationId, createdAt }
```

--------------------------------

### Gönderiye Yorum Yaz

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/getting-started.md

Belirli bir gönderiye yorum yazmak için `/api/v1/posts/POST_ID/comments` uç noktasına POST isteği yapın. Bu işlem `comments:write` yetkisi gerektirir.

```curl
# Bir gönderiye yorum (comments:write yetkisi gerekir)
curl -X POST https://dev.prototurk.com/api/v1/posts/POST_ID/comments \
  -H "Authorization: Bearer ptk_live_xxx" \
  -H "content-type: application/json" \
  -d '{"text": "Merhaba! Bu otomatik bir yanıt."}'
```

--------------------------------

### Send Message

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/dm.md

Sends a text-only reply to a conversation. The bot must already be a participant in the conversation. A `201 Created` response is returned upon successful sending.

```APIDOC
## POST /dm/conversations/:id/messages

### Description
Konuşmaya bot adına yanıt gönderir (text-only). Bot **zaten katılımcı olmalı**.

### Method
POST

### Endpoint
/dm/conversations/:id/messages

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the conversation to reply to.

#### Request Body
- **text** (string) - Required - The content of the message to send.

### Request Example
```bash
curl -X POST https://dev.prototurk.com/api/v1/dm/conversations/019e…/messages \
  -H "Authorization: Bearer ptk_live_xxx" \
  -H "content-type: application/json" \
  -d '{"text": "İyiyim, teşekkürler! Sana nasıl yardımcı olabilirim?"}'
```

### Request Example (JavaScript)
```javascript
const sent = await api(`/dm/conversations/${conversationId}/messages`, {
  method: 'POST',
  body: JSON.stringify({ text: 'İyiyim, teşekkürler!' }),
});
// { id, conversationId, createdAt }
```

### Response
#### Success Response (201 Created)
- **id** (string) - The ID of the sent message.
- **conversationId** (string) - The ID of the conversation.
- **createdAt** (string) - Timestamp when the message was created.

#### Response Example
```json
{
  "id": "019e…",
  "conversationId": "019e…",
  "createdAt": "2026-06-07T12:01:00.000Z"
}
```
```

--------------------------------

### Node.js (Express) Webhook Signature Verification

Source: https://github.com/iosmand/prototurk-api-docs/blob/main/api/webhooks.md

Verifies the HMAC-SHA256 signature of incoming webhook requests using Express. Requires raw request body and timing-safe comparison for security. Handles replay protection by checking the timestamp.

```javascript
import express from 'express';
import crypto from 'node:crypto';

const app = express();
const SECRET = process.env.PROTOTURK_WEBHOOK_SECRET!;

// Ham gövde şart — JSON parse'tan ÖNCE.
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('X-Prototurk-Signature') ?? '';
  const m = header.match(/^t=(\d+),v1=([0-9a-f]+)$/);
  if (!m) return res.status(400).end();
  const [, t, sig] = m;

  // Replay koruması: 5 dakikadan eski imzaları reddet.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.status(400).end();

  const expected = crypto
    .createHmac('sha256', SECRET)
    .update(`${t}.${req.body}`) // req.body bir Buffer (ham)
    .digest('hex');

  const ok = 
    sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  if (!ok) return res.status(401).end();

  const { events } = JSON.parse(req.body.toString('utf8'));
  for (const ev of events) handle(ev); // idempotent: ev.id ile dedup
  res.status(200).end();
});

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.