API

هذه ترجمة. النسخة الألمانية هي المعتمدة. وحيثما اختلف هذا النص عنها، يسري النص الألماني. يمكنك تغيير اللغة أسفل الصفحة.

المحتويات

نظرة عامة

يتيح v2 لبرامجك الخاصة التحدث إلى tellmelo: مفتاح لكل طلب، وJSON في الرد، وكل القوائم تُقسَّم إلى صفحات بالطريقة نفسها. تسري القواعد نفسها كما في التطبيق.

كل مسار يبدأ بـ/api/v2 على عنوان هذا الخادم.
الطلبات والردود بصيغة JSON بترميز UTF-8. أسماء الحقول والرموز والقيم إنجليزية وتبقى إنجليزية.
يعمل المفتاح بصفته حسابك: ما لا تراه في التطبيق لا يستطيع قراءته أيضًا.

https://tellmelo.com/api/v2

بداية سريعة

أنشئ مفتاحًا في «الإعدادات ← التطبيق والبيانات ← API» وانسخه. يُعرض مرة واحدة فقط.
استدعِ الجذر به. يُظهر الرد الإصدار وحقوق المفتاح والطلبات المتبقية في هذه الدقيقة.
كل المسارات تعمل بالطريقة نفسها: المفتاح في الترويسة، وJSON في الرد، وitems وnext للقوائم.

curl -H "Authorization: Bearer tm_key_…" https://tellmelo.com/api/v2

{
  "name": "tellmelo",
  "version": "2.10",
  "scope": "read write",
  "rateLimit": {
    "limit": 120,
    "remaining": 117
  },
  "docs": "/legal/api",
  "spec": "/api/v2/openapi.json"
}

التالي: /me لملفك الشخصي، و/posts للمنشورات العامة، و/feed لخلاصتك.

جرّبه

اختر مهمة، واملأ الحقول، وانسخ الطلب أو أرسله من هنا. الكتابة تطلب التأكيد أولًا. تقرأ الشيفرة المفتاح من TELLMELO_KEY.

المهمة

read إصدار API واسم هذا الخادم.

curl \
  -H "Authorization: Bearer $TELLMELO_KEY" \
  "https://tellmelo.com/api/v2"

مفتاحكيبقى في هذه الصفحة فقط حتى تغلقها.

مفتاحك

مفتاح واحد لكل حساب. يبدأ بـtm_key_ ويُعرض مرة واحدة فقط. فقدته؟ أنشئ مفتاحًا جديدًا؛ يتوقف القديم عن العمل.

تنشئه في «الإعدادات ← التطبيق والبيانات ← API». ويُرسل في ترويسة الطلب:

curl -H "Authorization: Bearer tm_key_…" \
  https://tellmelo.com/api/v2/posts

أو، إن كان ذلك أسهل، في ترويسة خاصة به:

curl -H "X-Tellmelo-Key: tm_key_…" https://tellmelo.com/api/v2

ليس في عنوان URL: سينتهي به الأمر في السجلات وسجل المتصفح.

المفتاح نفسه يحمّل الصور: كل url يشير إلى /api/media؛ أرسل المفتاح في الترويسة هناك أيضًا.

curl -H "Authorization: Bearer tm_key_…" \
  -o picture.webp "https://tellmelo.com/api/media?id=…"

ما يمكن للمفتاح فعله

للمفتاح أحد حقّين، وكل مسار أدناه يذكر الحق الذي يحتاجه:

read: القراءة. المنشورات العامة والملفات الشخصية والمجموعات والوسوم، إضافة إلى خلاصتك وإشعاراتك ورسائلك.
write: الفعل. النشر والرد والتصويت وإرسال الرسائل والمتابعة والانضمام والحظر وتعليم الإشعارات كمقروءة.

ما لا يستطيعه أي مفتاح

لا يصل أي مفتاح إلى كلمة المرور أو البريد الإلكتروني أو نوع الحساب أو المكان أو الدور أو الحذف أو الجلسات أو أجهزة الإشعارات أو المفاتيح الأخرى، ولا إلى الإدارة أو قيادة المجموعات. ما تحميه كلمة المرور لا يستطيعه أي مفتاح.

الطلبات والردود

JSON في كل مكان. كل رد هو application/json بترميز UTF-8، بما في ذلك الأخطاء. الصور وحدها تأتي صورًا.
ما ترسله. يحمل POST حقوله بصيغة JSON في المحتوى. إذا وُجد حقل في عنوان URL أيضًا فالمحتوى هو الذي يُعتمد.
الأوقات بالمللي ثانية منذ 1 يناير 1970، بتوقيت UTC.
المعرّفات سلاسل نصية. قارنها كاملة فقط.
كل حقل موجود دائمًا. ما ينقص قيمته null؛ ويمكن أن تكون القوائم فارغة.
النصوص نص عادي، تمامًا كما كُتبت. #الوسوم و@الأسماء والروابط تبقى كما هي، وكذلك الرموز التعبيرية الخاصة بالخادم بصيغة :name:؛ صورها مدرجة في /emojis.
الصور عناوين نسبية، /api/media?id=…. دون المفتاح في الترويسة تحصل على 401.

الصفحات

كل قائمة تقبل limit وcursor وتردّ بـitems وnext. أعد next بوصفه cursor لتحصل على الصفحة التالية؛ وعندما يكون next فارغًا تكون قد انتهيت. المؤشر معتم: لا تحلّله ولا تنشئه بنفسك.

{ "items": [ … ], "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx" }

curl -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/posts?limit=20&cursor=MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"

دون limit تحصل على 20 إدخالًا، و50 كحد أقصى. بعض القوائم لا تُقسَّم إلى صفحات؛ قيمة next فيها دائمًا null.

الجديد فقط

كل رد يحمل ETag. أعِده في المرة القادمة بوصفه If-None-Match: إن لم يتغير شيء تحصل على 304 دون محتوى.

ETag: W/"3Qk1mJ7fQe2Yb0sVxT9aL4pNdRc"
If-None-Match: W/"3Qk1mJ7fQe2Yb0sVxT9aL4pNdRc"  →  304

الاستثناءات: ليس لـ/feed قيمة ETag لأن ترتيبه يتغير باستمرار، وعمليات الكتابة لا تردّ أبدًا بـ304.

الحدود

يمكن للمفتاح إجراء 120 طلبًا في الدقيقة، و600 مع اشتراك «منظمة»، ما لم تحدد الإدارة غير ذلك. فوق ذلك تحصل على 429 ولا يُنفَّذ شيء. انتظر دقيقة وأرسل الطلب مجددًا.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1758624060

تُحتسب عمليات الكتابة أيضًا ضمن حدود التطبيق، مثل عدد المنشورات في بضع دقائق. وهذا أيضًا يردّ بـ429 مع rate_limited.

الترويسات

باستثناء المفتاح، لا ترويسة مطلوبة.

ما ترسله

الترويسة	المعنى
`Authorization`	يحمل المفتاح: `Bearer tm_key_…`. الطريقة المعتادة.
`X-Tellmelo-Key`	المفتاح، بديلًا عن `Authorization`.
`Content-Type`	`application/json`، لطلب له محتوى.
`If-None-Match`	قيمة `ETag` من آخر رد. إن لم يتغير شيء منذ ذلك فالرد `304` دون محتوى.

ما يعود

الترويسة	المعنى
`ETag`	بصمة هذا الرد (`W/`). أعِدها بوصفها `If-None-Match`.
`X-RateLimit-Limit`	كم طلبًا يمكن لهذا المفتاح إجراؤه في الدقيقة.
`X-RateLimit-Remaining`	كم بقي منها في الدقيقة الحالية.
`X-RateLimit-Reset`	متى تبدأ الدقيقة التالية، بالثواني منذ 1970، بتوقيت UTC.
`X-Tellmelo-Scope`	ما يمكن لهذا المفتاح فعله: `read` أو `read write`.
`Retry-After`	مع `429`: كم ثانية تنتظر قبل أن تسأل مجددًا.
`WWW-Authenticate`	عند `401` دون مفتاح: `Bearer`.
`Cache-Control`	`no-store`: لا يجوز لأي وكيل تخزين الرد مؤقتًا. ويمكنك مع ذلك التحقق منه بـ`ETag`.

عندما لا ينجح شيء

تأتي الأخطاء بصيغة JSON: رمز إنجليزي ثابت في error لبرنامجك وجملة في message للبشر، مع رمز الحالة المناسب. قارن الرمز فقط؛ فالجملة قد تتغير.

{ "error": "rate_limited",
  "message": "Too many requests. Try again in a minute.",
  "limit": 120 }

بعض الأخطاء تحمل حقلًا إضافيًا: docs مع 401 بسبب غياب المفتاح، وlimit مع 429.

الحالة	الرمز	المعنى
`400`	`bad_request`	لا يمكن قراءة الطلب، أو ينقص حقل مطلوب، أو القيمة غير مسموحة.
`401`	`key_missing`	لا يوجد مفتاح في الترويسة.
`401`	`key_invalid`	المفتاح غير صالح: خطأ في الكتابة، أو استُبدل، أو الحساب محظور.
`401`	`unauthorized`	رُفض بوصفه غير مسجّل الدخول، لسبب غير المفتاح.
`403`	`scope_missing`	ينقص المفتاح الحق المطلوب، وغالبًا `write`.
`403`	`account_data_locked`	بيانات الحساب مثل كلمة المرور أو البريد الإلكتروني أو الحذف خارج نطاق المفاتيح.
`403`	`forbidden`	لا يجوز لحسابك فعل ذلك، مثلًا بسبب حق مسحوب أو حظر.
`404`	`unknown_path`	لا يوجد مسار كهذا، أو ليس بهذه الطريقة.
`404`	`not_found`	غير موجود، أو لا يجوز لك رؤيته.
`409`	`conflict`	يتعارض مع ما هو موجود بالفعل، مثل اسم مأخوذ.
`413`	`too_large`	كبير جدًا على هذا الخادم.
`422`	`unprocessable`	مقروء، لكنه غير ممكن بهذا الشكل.
`429`	`rate_limited`	طلبات كثيرة جدًا. لم يحدث شيء؛ انتظر وحاول مجددًا.
`500`	`internal_error`	حدث خطأ ما على الخادم.

الإصدارات

الإصدار موجود في المسار. ما دام مكتوبًا v2 تبقى المسارات والحقول كما هي؛ تُضاف أشياء جديدة فقط.

الإضافات ترفع الرقم الثاني. كل مسار يذكر منذ متى يوجد.

انتهى /api/v1/: المسارات القديمة تردّ بـ410 وتذكر الطريق الجديد في المحتوى.

نقاط النهاية

كل المسارات بنظرة واحدة، ثم كل واحد مع مثال.

المسار	الحق	لأي غرض
المدخل
GET`/api/v2`	`read`	إصدار API واسم هذا الخادم.
المنشورات
GET`/api/v2/posts`	`read`	المنشورات العامة، الأحدث أولًا.
GET`/api/v2/posts/{id}`	`read`	منشور واحد، بحسب `id`.
POST`/api/v2/posts`	`write`	نشر منشور.
DELETE`/api/v2/posts/{id}`	`write`	إزالة أحد منشوراتك.
الردود
GET`/api/v2/posts/{id}/replies`	`read`	الردود على منشور، دون الحسابات المحظورة.
POST`/api/v2/posts/{id}/replies`	`write`	الرد على منشور.
الاستطلاعات
POST`/api/v2/posts/{id}/vote`	`write`	المشاركة في استطلاع.
الملفات الشخصية
GET`/api/v2/profiles/{handle}`	`read`	ملف شخصي، بحسب اسمه المختصر.
GET`/api/v2/profiles/{handle}/posts`	`read`	المنشورات العامة لملف شخصي واحد، الأحدث أولًا.
المجموعات
GET`/api/v2/communities`	`read`	المجموعات المفتوحة على هذا الخادم.
GET`/api/v2/communities/{id}`	`read`	مجموعة واحدة، بحسب `id`.
GET`/api/v2/communities/{id}/posts`	`read`	المنشورات العامة لمجموعة واحدة، الأحدث أولًا.
استكشاف
GET`/api/v2/tags`	`read`	الوسوم الرائجة حاليًا.
GET`/api/v2/search`	`read`	بحث في المنشورات والأسماء والأسماء المختصرة والوسوم.
GET`/api/v2/emojis`	`read`	الرموز التعبيرية الخاصة بالخادم، مع عناوين صورها.
حسابك
GET`/api/v2/me`	`read`	ملفك الشخصي، مع `id` الذي تتوقعه المسارات الأخرى.
GET`/api/v2/feed`	`read`	خلاصتك، كما يجمعها التطبيق.
الإشعارات
GET`/api/v2/notifications`	`read`	إشعاراتك، الأحدث أولًا.
POST`/api/v2/notifications/read`	`write`	تعليم إشعاراتك كمقروءة.
الرسائل
GET`/api/v2/conversations`	`read`	صندوق رسائلك: سطر لكل محادثة، الأحدث أولًا.
GET`/api/v2/conversations/{with}/messages`	`read`	رسائل محادثة واحدة، الأحدث أولًا.
POST`/api/v2/conversations/{with}/messages`	`write`	إرسال رسالة في محادثة.
POST`/api/v2/conversations/{with}/read`	`write`	تعليم كل رسائل محادثة كمقروءة.
العلاقات
POST`/api/v2/relations`	`write`	إعجاب، حفظ، إعادة نشر، متابعة، انضمام، حظر، كتم، بحسب `kind`.

المدخل

الطلب الأول لكل برنامج: هل يعمل المفتاح، وماذا يجوز له أن يفعل؟

GET`/api/v2`

إصدار API واسم هذا الخادم.

الحق read
مع ETag
منذ v2.0

دون شرطة مائلة في النهاية: /api/v2/ يُعيد التوجيه إلى /api/v2 بـ308، وليس كل برنامج يتبع ذلك.

مثال على الطلب

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2"

الرد

يردّ بـService واحد.

مثال

{
  "name": "tellmelo",
  "version": "2.10",
  "scope": "read write",
  "rateLimit": {
    "limit": 120,
    "remaining": 117
  },
  "docs": "/legal/api",
  "spec": "/api/v2/openapi.json"
}

الحالات الممكنة: 200304401429

المنشورات

قراءة المنشورات العامة ونشر منشوراتك وإزالتها مجددًا.

GET`/api/v2/posts`

المنشورات العامة، الأحدث أولًا.

الحق read
مقسَّم إلى صفحات
مع ETag
منذ v2.0

في المسارات العامة تكون counts.likes وcounts.reposts دائمًا 0 وpinned هي false.

منشورات المجموعات ليست هنا بل في /communities/{id}/posts.

المعاملات

الاسم	النوع	المعنى
`limit`في الاستعلام	`integer`اختياري	عدد الإدخالات في الصفحة: 20 افتراضيًا، 50 كحد أقصى.
`cursor`في الاستعلام	`string`اختياري	قيمة `next` من الإجابة السابقة. دونها من البداية.

مثال على الطلب

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/posts?limit=20"

الرد

يردّ بصفحة من Post، بوصفها `items` و`next`.

مثال

{
  "items": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

الحالات الممكنة: 200304401429

GET`/api/v2/posts/{id}`

منشور واحد، بحسب id.

الحق read
مع ETag
منذ v2.0

في المسارات العامة تكون counts.likes وcounts.reposts دائمًا 0 وpinned هي false.

منشورات المجموعات ليست هنا بل في /communities/{id}/posts.

المعاملات

الاسم	النوع	المعنى
`id`في المسار	`string`مطلوب	`id` منشور.

مثال على الطلب

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1"

الرد

يردّ بـPost واحد.

مثال

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "text": "The bees are back in the garden 🐝 #garden",
  "kind": "poll",
  "author": {
    "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
    "handle": "mara",
    "name": "Mara 🌻",
    "verified": true,
    "accountKind": "person"
  },
  "community": {
    "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
    "name": "Urban Gardening"
  },
  "media": [
    {
      "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
      "kind": "image",
      "poster": null
    }
  ],
  "poll": {
    "options": [
      {
        "text": "Lavender",
        "votes": 12
      },
      {
        "text": "Sunflowers",
        "votes": 7
      },
      {
        "text": "Clover",
        "votes": 3
      }
    ],
    "total": 22,
    "multiple": false,
    "endsAt": 1758710400000,
    "running": true,
    "resultsVisible": true,
    "myVotes": [
      0
    ]
  },
  "quotes": null,
  "continues": null,
  "counts": {
    "replies": 4,
    "likes": 31,
    "reposts": 2
  },
  "pinned": false,
  "createdAt": 1758624000000
}

الحالات الممكنة: 200304400401404429

POST`/api/v2/posts`

نشر منشور.

الحق write
منذ v2.0

يحتاج المنشور إلى نص أو استطلاع. الطول وخيارات الاستطلاع والوتيرة يحددها الخادم؛ وما زاد على ذلك يعطيك 400 أو 429.

لا يمكن إرفاق الصور عبر API بعد، فقط في التطبيق.

المعاملات

الاسم	النوع	المعنى
`text`في المحتوى	`string`اختياري	نص المنشور أو الرد أو الرسالة.
`community`في المحتوى	`string`اختياري	`id` المجموعة التي يدخلها المنشور. دونه خارج كل المجموعات.
`quotes`في المحتوى	`string`اختياري	`id` المنشور الذي يقتبسه هذا المنشور.
`poll`في المحتوى	`string[]`اختياري	خيارات الإجابة كقائمة نصوص.

مثال على الطلب

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"The bees are back in the garden 🐝 #garden"}' \
  "https://tellmelo.com/api/v2/posts"

الرد

يردّ بـCreated واحد.

مثال

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "scheduledFor": null,
  "deleteAt": null
}

الحالات الممكنة: 200400401403429

DELETE`/api/v2/posts/{id}`

إزالة أحد منشوراتك.

الحق write
منذ v2.0

المعاملات

الاسم	النوع	المعنى
`id`في المسار	`string`مطلوب	`id` منشور.

مثال على الطلب

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1"

الرد

يردّ بـOk واحد.

مثال

{
  "ok": true
}

الحالات الممكنة: 200400401403404429

الردود

الردود تحت منشور، كقائمة مع parentId.

GET`/api/v2/posts/{id}/replies`

الردود على منشور، دون الحسابات المحظورة.

الحق read
مقسَّم إلى صفحات
مع ETag
منذ v2.0

القائمة مسطّحة وبترتيب الكتابة؛ وparentId يحوّلها إلى شجرة. تحتوي الصفحة دائمًا سلاسل كاملة. تُستبعد ردود الحسابات المحظورة.

المعاملات

الاسم	النوع	المعنى
`id`في المسار	`string`مطلوب	`id` منشور.
`limit`في الاستعلام	`integer`اختياري	عدد الإدخالات في الصفحة: 20 افتراضيًا، 50 كحد أقصى.
`cursor`في الاستعلام	`string`اختياري	قيمة `next` من الإجابة السابقة. دونها من البداية.

مثال على الطلب

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/replies?limit=20"

الرد

يردّ بصفحة من Reply، بوصفها `items` و`next`.

مثال

{
  "items": [
    {
      "id": "9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a",
      "text": "Same here, the lavender is full of them.",
      "kind": "post",
      "author": {
        "id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
        "handle": "jon",
        "name": "Jon",
        "verified": false,
        "accountKind": "person"
      },
      "community": null,
      "media": [],
      "poll": null,
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 0,
        "likes": 3,
        "reposts": 0
      },
      "pinned": false,
      "createdAt": 1758624600000,
      "postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "parentId": null
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

الحالات الممكنة: 200304400401404429

POST`/api/v2/posts/{id}/replies`

الرد على منشور.

الحق write
منذ v2.0

في الوضع البطيء، رد واحد لكل شخص كل 10 دقائق، وإلا 429. المؤلف والحسابات التي يتابعها مستثنون.

المعاملات

الاسم	النوع	المعنى
`id`في المسار	`string`مطلوب	`id` منشور.
`text`في المحتوى	`string`مطلوب	نص المنشور أو الرد أو الرسالة.
`parentId`في المحتوى	`string`اختياري	`id` الرد الذي يجيب عنه هذا الرد. دونه مباشرة إلى المنشور.

مثال على الطلب

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"Same here, the lavender is full of them."}' \
  "https://tellmelo.com/api/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/replies"

الرد

يردّ بـCreated واحد.

مثال

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "scheduledFor": null,
  "deleteAt": null
}

الحالات الممكنة: 200400401403404429

الاستطلاعات

الاستطلاع منشور قيمة poll فيه مضبوطة. وللتصويت مسار خاص.

POST`/api/v2/posts/{id}/vote`

المشاركة في استطلاع.

الحق write
منذ v2.0

الأصوات لكل خيار تكون null حتى تصوّت أو ينتهي الاستطلاع. total موجود دائمًا.

المعاملات

الاسم	النوع	المعنى
`id`في المسار	`string`مطلوب	`id` منشور.
`option`في المحتوى	`integer`مطلوب	أي خيار، العدّ من 0. في الاختيار المتعدد استدعِ مرة لكل خيار.
`retract`في المحتوى	`boolean`اختياري	`true` يسحب الصوت.

مثال على الطلب

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"option":0}' \
  "https://tellmelo.com/api/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/vote"

الرد

يردّ بـOk واحد.

مثال

{
  "ok": true
}

الحالات الممكنة: 200400401403404429

الملفات الشخصية

الملفات الشخصية العامة بحسب اسمها المختصر، وما نشرته.

GET`/api/v2/profiles/{handle}`

ملف شخصي، بحسب اسمه المختصر.

الحق read
مع ETag
منذ v2.0

المعاملات

الاسم	النوع	المعنى
`handle`في المسار	`string`مطلوب	الاسم المختصر لملف شخصي.

مثال على الطلب

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/profiles/mara"

الرد

يردّ بـProfile واحد.

مثال

{
  "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "handle": "mara",
  "name": "Mara 🌻",
  "verified": true,
  "accountKind": "person",
  "about": "Beekeeper, allotment, too many seeds. :tellmelo:",
  "website": "https://mara-imkerei.example/",
  "websiteVerified": true,
  "followers": 148,
  "createdAt": 1750848000000
}

الحالات الممكنة: 200304400401404429

GET`/api/v2/profiles/{handle}/posts`

المنشورات العامة لملف شخصي واحد، الأحدث أولًا.

الحق read
مقسَّم إلى صفحات
مع ETag
منذ v2.0

في المسارات العامة تكون counts.likes وcounts.reposts دائمًا 0 وpinned هي false.

منشورات المجموعات ليست هنا بل في /communities/{id}/posts.

المعاملات

الاسم	النوع	المعنى
`handle`في المسار	`string`مطلوب	الاسم المختصر لملف شخصي.
`limit`في الاستعلام	`integer`اختياري	عدد الإدخالات في الصفحة: 20 افتراضيًا، 50 كحد أقصى.
`cursor`في الاستعلام	`string`اختياري	قيمة `next` من الإجابة السابقة. دونها من البداية.

مثال على الطلب

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/profiles/mara/posts?limit=20"

الرد

يردّ بصفحة من Post، بوصفها `items` و`next`.

مثال

{
  "items": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

الحالات الممكنة: 200304400401404429

المجموعات

المجموعات المفتوحة ومنشوراتها.

GET`/api/v2/communities`

المجموعات المفتوحة على هذا الخادم.

الحق read
مع ETag
منذ v2.0

مرتّبة حسب عدد الأعضاء وغير مقسّمة إلى صفحات؛ next دائمًا null.

المعاملات

الاسم	النوع	المعنى
`limit`في الاستعلام	`integer`اختياري	عدد الإدخالات في الصفحة: 20 افتراضيًا، 50 كحد أقصى.

مثال على الطلب

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/communities?limit=20"

الرد

يردّ بصفحة من Community، بوصفها `items` و`next`.

مثال

{
  "items": [
    {
      "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
      "name": "Urban Gardening",
      "description": "Balconies, allotments, rooftops: whatever grows.",
      "tags": [
        "garden",
        "bees"
      ],
      "members": 312,
      "joinPolicy": "open",
      "visibility": "open"
    }
  ],
  "next": null
}

الحالات الممكنة: 200304401429

GET`/api/v2/communities/{id}`

مجموعة واحدة، بحسب id.

الحق read
مع ETag
منذ v2.0

المعاملات

الاسم	النوع	المعنى
`id`في المسار	`string`مطلوب	`id` مجموعة.

مثال على الطلب

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60"

الرد

يردّ بـCommunity واحد.

مثال

{
  "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
  "name": "Urban Gardening",
  "description": "Balconies, allotments, rooftops: whatever grows.",
  "tags": [
    "garden",
    "bees"
  ],
  "members": 312,
  "joinPolicy": "open",
  "visibility": "open"
}

الحالات الممكنة: 200304400401404429

GET`/api/v2/communities/{id}/posts`

المنشورات العامة لمجموعة واحدة، الأحدث أولًا.

الحق read
مقسَّم إلى صفحات
مع ETag
منذ v2.0

في المسارات العامة تكون counts.likes وcounts.reposts دائمًا 0 وpinned هي false.

المعاملات

الاسم	النوع	المعنى
`id`في المسار	`string`مطلوب	`id` مجموعة.
`limit`في الاستعلام	`integer`اختياري	عدد الإدخالات في الصفحة: 20 افتراضيًا، 50 كحد أقصى.
`cursor`في الاستعلام	`string`اختياري	قيمة `next` من الإجابة السابقة. دونها من البداية.

مثال على الطلب

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/posts?limit=20"

الرد

يردّ بصفحة من Post، بوصفها `items` و`next`.

مثال

{
  "items": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

الحالات الممكنة: 200304400401404429

استكشاف

الرائج والبحث والرموز التعبيرية الخاصة بالخادم.

GET`/api/v2/tags`

الوسوم الرائجة حاليًا.

الحق read
مع ETag
منذ v2.0

10 وسوم رائجة كحد أقصى بحسب النقاط: كل استخدام يُحتسب 1 وينخفض إلى النصف كل 3 أيام، والحساب الواحد يُحتسب 3 كحد أقصى في اليوم. posts هي النقاط مقرّبة. limit يقصّر القائمة فقط. الوسوم التي يبرزها الفريق قد تكون أعلى.

المعاملات

الاسم	النوع	المعنى
`limit`في الاستعلام	`integer`اختياري	عدد الإدخالات في الصفحة: 20 افتراضيًا، 50 كحد أقصى.

مثال على الطلب

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/tags?limit=10"

الرد

يردّ بصفحة من Tag، بوصفها `items` و`next`.

مثال

{
  "items": [
    {
      "tag": "garden",
      "posts": 58
    }
  ],
  "next": null
}

الحالات الممكنة: 200304401429

GET`/api/v2/search`

بحث في المنشورات والأسماء والأسماء المختصرة والوسوم.

الحق read
مع ETag
منذ v2.0

يبحث في المحتوى العام فقط: المنشورات خارج المجموعات والملفات الشخصية والوسوم. يسري limit على كل نوع.

المعاملات

الاسم	النوع	المعنى
`q`في الاستعلام	`string`مطلوب	الكلمات المبحوث عنها.
`type`في الاستعلام	`string`اختياري	أي نوع من النتائج. دونه كل الأنواع.`allpostsprofilestags`
`limit`في الاستعلام	`integer`اختياري	عدد الإدخالات في الصفحة: 20 افتراضيًا، 50 كحد أقصى.

مثال على الطلب

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/search?q=garden&type=posts"

الرد

يردّ بـSearchResult واحد.

مثال

{
  "posts": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "profiles": [
    {
      "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "handle": "mara",
      "name": "Mara 🌻",
      "verified": true,
      "accountKind": "person"
    }
  ],
  "tags": [
    {
      "tag": "garden",
      "posts": 58
    }
  ]
}

الحالات الممكنة: 200304400401429

GET`/api/v2/emojis`

الرموز التعبيرية الخاصة بالخادم، مع عناوين صورها.

الحق read
مع ETag
منذ v2.1

يظهر الرمز التعبيري في النصوص بصيغة :name:. استبدله بالصورة من هذه القائمة؛ الأسماء غير المعروفة تبقى نصًا.

مثال على الطلب

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/emojis"

الرد

يردّ بصفحة من Emoji، بوصفها `items` و`next`.

مثال

{
  "items": [
    {
      "name": "tellmelo",
      "url": "/api/media?id=e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b"
    }
  ],
  "next": null
}

الحالات الممكنة: 200304401429

حسابك

ملفك الشخصي وخلاصتك.

GET`/api/v2/me`

ملفك الشخصي، مع id الذي تتوقعه المسارات الأخرى.

الحق read
مع ETag
منذ v2.0

مثال على الطلب

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/me"

الرد

يردّ بـProfile واحد.

مثال

{
  "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "handle": "mara",
  "name": "Mara 🌻",
  "verified": true,
  "accountKind": "person",
  "about": "Beekeeper, allotment, too many seeds. :tellmelo:",
  "website": "https://mara-imkerei.example/",
  "websiteVerified": true,
  "followers": 148,
  "createdAt": 1750848000000
}

الحالات الممكنة: 200304401429

GET`/api/v2/feed`

خلاصتك، كما يجمعها التطبيق.

الحق read
مقسَّم إلى صفحات
منذ v2.0

بلا ETag لأن الترتيب يتغير باستمرار. القائمة التي بدأتها تبقى كما هي حتى نهايتها.

المعاملات

الاسم	النوع	المعنى
`tab`في الاستعلام	`string`اختياري	أي خلاصة: `for-you` أو `following` أو `latest` أو `bookmarks`. `latest` افتراضيًا.`for-youfollowinglatestbookmarks`
`tag`في الاستعلام	`string`اختياري	فقط المنشورات عن هذا الوسم: المكتوبة به أو التي تعرّف عليه الخادم فيها. دونه بلا تصفية.
`limit`في الاستعلام	`integer`اختياري	عدد الإدخالات في الصفحة: 20 افتراضيًا، 50 كحد أقصى.
`cursor`في الاستعلام	`string`اختياري	قيمة `next` من الإجابة السابقة. دونها من البداية.

مثال على الطلب

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/feed?tab=following&limit=20"

الرد

يردّ بصفحة من Post، بوصفها `items` و`next`.

مثال

{
  "items": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

الحالات الممكنة: 200400401429

الإشعارات

ما حدث حول حسابك، صفحة بعد صفحة.

GET`/api/v2/notifications`

إشعاراتك، الأحدث أولًا.

الحق read
مقسَّم إلى صفحات
مع ETag
منذ v2.0

القراءة لا تعلّم شيئًا كمقروء؛ POST /notifications/read يفعل ذلك. الأحداث من النوع نفسه على المنشور نفسه تتشارك سطرًا واحدًا؛ وmore يذكر عددها.

المعاملات

الاسم	النوع	المعنى
`limit`في الاستعلام	`integer`اختياري	عدد الإدخالات في الصفحة: 20 افتراضيًا، 50 كحد أقصى.
`cursor`في الاستعلام	`string`اختياري	قيمة `next` من الإجابة السابقة. دونها من البداية.

مثال على الطلب

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/notifications?limit=20"

الرد

يردّ بصفحة من Notification، بوصفها `items` و`next`.

مثال

{
  "items": [
    {
      "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
      "kind": "like",
      "text": null,
      "actor": {
        "handle": "jon",
        "name": "Jon"
      },
      "postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "read": false,
      "more": 2,
      "createdAt": 1758624300000,
      "updatedAt": 1758624900000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

الحالات الممكنة: 200304401429

POST`/api/v2/notifications/read`

تعليم إشعاراتك كمقروءة.

الحق write
منذ v2.0

مثال على الطلب

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/notifications/read"

الرد

يردّ بـOk واحد.

مثال

{
  "ok": true
}

الحالات الممكنة: 200401403429

الرسائل

صندوق رسائلك ومحادثاتك. تُسمّى المحادثة باسم الحساب الآخر.

GET`/api/v2/conversations`

صندوق رسائلك: سطر لكل محادثة، الأحدث أولًا.

الحق read
مقسَّم إلى صفحات
مع ETag
منذ v2.0

المعاملات

الاسم	النوع	المعنى
`limit`في الاستعلام	`integer`اختياري	عدد الإدخالات في الصفحة: 20 افتراضيًا، 50 كحد أقصى.
`cursor`في الاستعلام	`string`اختياري	قيمة `next` من الإجابة السابقة. دونها من البداية.

مثال على الطلب

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/conversations?limit=20"

الرد

يردّ بصفحة من Conversation، بوصفها `items` و`next`.

مثال

{
  "items": [
    {
      "with": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
      "handle": "jon",
      "name": "Jon",
      "excerpt": "See you on Saturday at the market!",
      "truncated": false,
      "fromMe": true,
      "lastMessageId": "7c6b5a49-3827-4165-9f0e-d1c2b3a49586",
      "unread": 0,
      "updatedAt": 1758624060000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

الحالات الممكنة: 200304401429

GET`/api/v2/conversations/{with}/messages`

رسائل محادثة واحدة، الأحدث أولًا.

الحق read
مقسَّم إلى صفحات
مع ETag
منذ v2.0

القراءة لا تعلّم شيئًا كمقروء؛ POST /conversations/{with}/read يفعل ذلك.

المعاملات

الاسم	النوع	المعنى
`with`في المسار	`string`مطلوب	`id` الحساب الآخر. ليس للمحادثة `id` خاص بها.
`limit`في الاستعلام	`integer`اختياري	عدد الإدخالات في الصفحة: 20 افتراضيًا، 50 كحد أقصى.
`cursor`في الاستعلام	`string`اختياري	قيمة `next` من الإجابة السابقة. دونها من البداية.

مثال على الطلب

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/conversations/a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05/messages?limit=20"

الرد

يردّ بصفحة من Message، بوصفها `items` و`next`.

مثال

{
  "items": [
    {
      "id": "7c6b5a49-3827-4165-9f0e-d1c2b3a49586",
      "text": "See you on Saturday at the market!",
      "from": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "to": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
      "read": true,
      "media": [],
      "replyTo": null,
      "createdAt": 1758624060000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

الحالات الممكنة: 200304400401404429

POST`/api/v2/conversations/{with}/messages`

إرسال رسالة في محادثة.

الحق write
منذ v2.0

تسري قواعد التطبيق: من حظرك لا يمكن الوصول إليه، وإعدادات الطرف الآخر تُحتسب.

لا يمكن إرفاق الصور عبر API بعد، فقط في التطبيق.

المعاملات

الاسم	النوع	المعنى
`with`في المسار	`string`مطلوب	`id` الحساب الآخر. ليس للمحادثة `id` خاص بها.
`text`في المحتوى	`string`مطلوب	نص المنشور أو الرد أو الرسالة.
`replyTo`في المحتوى	`string`اختياري	`id` رسالة سابقة في هذه المحادثة تجيب عنها هذه الرسالة. منذ 2.2.

مثال على الطلب

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"See you on Saturday at the market!"}' \
  "https://tellmelo.com/api/v2/conversations/a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05/messages"

الرد

يردّ بـOk واحد.

مثال

{
  "ok": true
}

الحالات الممكنة: 200400401403404429

POST`/api/v2/conversations/{with}/read`

تعليم كل رسائل محادثة كمقروءة.

الحق write
منذ v2.1

المعاملات

الاسم	النوع	المعنى
`with`في المسار	`string`مطلوب	`id` الحساب الآخر. ليس للمحادثة `id` خاص بها.

مثال على الطلب

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/conversations/a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05/read"

الرد

يردّ بـOk واحد.

مثال

{
  "ok": true
}

الحالات الممكنة: 200400401403404429

العلاقات

إعجاب، حفظ، إعادة نشر، متابعة، انضمام، حظر: مسار واحد، يُضبط ويُزال بـactive.

POST`/api/v2/relations`

إعجاب، حفظ، إعادة نشر، متابعة، انضمام، حظر، كتم، بحسب kind.

الحق write
منذ v2.0

target منشور مع like وsave وrepost، ومجموعة مع join، وحساب مع follow وblock وmute. active: false يزيل العلاقة.

المعاملات

الاسم	النوع	المعنى
`kind`في المحتوى	`string`مطلوب	أي علاقة: `like` أو `save` أو `repost` أو `follow` أو `join` أو `block` أو `mute` (منذ 2.2).`likesaverepostfollowjoinblockmute`
`target`في المحتوى	`string`مطلوب	`id` المنشور أو الملف الشخصي أو المجموعة، بحسب `kind`.
`active`في المحتوى	`boolean`اختياري	`true` يضبط العلاقة، و`false` يزيلها.

مثال على الطلب

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"kind":"like","target":"5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1","active":true}' \
  "https://tellmelo.com/api/v2/relations"

الرد

يردّ بـOk واحد.

مثال

{
  "ok": true
}

الحالات الممكنة: 200400401403429

الكائنات

كل الكائنات، حقلًا حقلًا. [] تعني قائمة.

`Service`

رد الجذر: من يردّ، وما يمكن لهذا المفتاح فعله.

الحقل	النوع	المعنى
`name`	`string`	دائمًا `tellmelo`.
`version`	`string`	إصدار API، مثل `2.1`.
`scope`	`string`	ما يمكن لهذا المفتاح فعله: `read` أو `read write`.
`rateLimit`	`RateLimit`	رصيد هذا المفتاح.
`docs`	`string`	مكان هذا التوثيق، كمسار على هذا الخادم.
`spec`	`string`	مكان الوصف المقروء آليًا.

مثال

{
  "name": "tellmelo",
  "version": "2.10",
  "scope": "read write",
  "rateLimit": {
    "limit": 120,
    "remaining": 117
  },
  "docs": "/legal/api",
  "spec": "/api/v2/openapi.json"
}

`RateLimit`

رصيد هذا المفتاح في الدقيقة الحالية.

الحقل	النوع	المعنى
`limit`	`integer`	الطلبات في الدقيقة.
`remaining`	`integer`	كم بقي في هذه الدقيقة.

مثال

{
  "limit": 120,
  "remaining": 117
}

`Post`

منشور، بالشكل نفسه في كل مكان.

الحقل	النوع	المعنى
`id`	`string`	معرّف المنشور.
`text`	`string`أو null	النص كما كُتب (`null` لمنشور هو استطلاع فقط أو صور فقط).
`kind`	`string`	ما هو المنشور. `post` — منشور بنص أو صور أو اقتباس. `poll` — منشور باستطلاع.
`author`	`ProfileBrief`	من كتبه.
`community`	`CommunityBrief`أو null	المجموعة التي كُتب فيها (`null` خارج كل المجموعات).
`media`	`Media[]`	صوره بالترتيب؛ فارغة إن لم توجد.
`poll`	`Poll`أو null	الاستطلاع (`null` إن لم يوجد).
`quotes`	`string`أو null	معرّف المنشور الذي يقتبسه هذا المنشور.
`continues`	`string`أو null	معرّف المنشور الذي يتابعه هذا المنشور، كإضافة.
`counts`	`Counts`	الردود والإعجابات وإعادات النشر.
`pinned`	`boolean`	هل هو مثبّت أعلى ملف مؤلفه الشخصي.
`createdAt`	`integer`	متى كُتب.

مثال

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "text": "The bees are back in the garden 🐝 #garden",
  "kind": "poll",
  "author": {
    "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
    "handle": "mara",
    "name": "Mara 🌻",
    "verified": true,
    "accountKind": "person"
  },
  "community": {
    "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
    "name": "Urban Gardening"
  },
  "media": [
    {
      "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
      "kind": "image",
      "poster": null
    }
  ],
  "poll": {
    "options": [
      {
        "text": "Lavender",
        "votes": 12
      },
      {
        "text": "Sunflowers",
        "votes": 7
      },
      {
        "text": "Clover",
        "votes": 3
      }
    ],
    "total": 22,
    "multiple": false,
    "endsAt": 1758710400000,
    "running": true,
    "resultsVisible": true,
    "myVotes": [
      0
    ]
  },
  "quotes": null,
  "continues": null,
  "counts": {
    "replies": 4,
    "likes": 31,
    "reposts": 2
  },
  "pinned": false,
  "createdAt": 1758624000000
}

`Reply`

رد تحت منشور: منشور بحقلين إضافيين.

كل حقول Post، وإضافة إلى ذلك:

الحقل	النوع	المعنى
`postId`	`string`	المنشور الذي تتعلق به المحادثة كلها.
`parentId`	`string`أو null	الرد الذي يجيب عنه هذا الرد (`null` إن كان يجيب عن المنشور مباشرة).

مثال

{
  "id": "9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a",
  "text": "Same here, the lavender is full of them.",
  "kind": "post",
  "author": {
    "id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
    "handle": "jon",
    "name": "Jon",
    "verified": false,
    "accountKind": "person"
  },
  "community": null,
  "media": [],
  "poll": null,
  "quotes": null,
  "continues": null,
  "counts": {
    "replies": 0,
    "likes": 3,
    "reposts": 0
  },
  "pinned": false,
  "createdAt": 1758624600000,
  "postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "parentId": null
}

`Counts`

كم ردًا وإعجابًا وإعادة نشر لمنشور ما.

الحقل	النوع	المعنى
`replies`	`integer`	الردود، كل المستويات معًا.
`likes`	`integer`	الإعجابات.
`reposts`	`integer`	إعادات النشر.

مثال

{
  "replies": 4,
  "likes": 31,
  "reposts": 2
}

`Media`

صورة لمنشور أو رسالة.

الحقل	النوع	المعنى
`url`	`string`	عنوان الصورة أو الفيديو، نسبةً إلى هذا الخادم. حمّله والمفتاح في الترويسة.
`kind`	`string`	`image` أو `video` أو `gif` (منذ 2.10). الفيديو وGIF ملفات MP4. `image` — صورة (WebP أو JPEG). `video` — فيديو بصيغة MP4، مع صوت. `gif` — GIF، كملف MP4 صامت يتكرر.
`poster`	`string`أو null	للفيديو وGIF عنوان صورة المعاينة، وإلا `null` (منذ 2.10).

مثال

{
  "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
  "kind": "image",
  "poster": null
}

`Poll`

استطلاع منشور.

الحقل	النوع	المعنى
`options`	`PollOption[]`	الإجابات بالترتيب. `option` في التصويت يُعد من 0.
`total`	`integer`	كل الأصوات معًا، موجود دائمًا.
`multiple`	`boolean`	هل يمكن اختيار أكثر من إجابة.
`endsAt`	`integer`أو null	متى ينتهي الاستطلاع (`null` إن كان بلا نهاية).
`running`	`boolean`	هل لا يزال التصويت ممكنًا.
`resultsVisible`	`boolean`	هل تُعرض الأصوات لكل إجابة (انظر `votes`).
`myVotes`	`integer[]`	الإجابات التي اخترتها، العدّ من 0.

مثال

{
  "options": [
    {
      "text": "Lavender",
      "votes": 12
    },
    {
      "text": "Sunflowers",
      "votes": 7
    },
    {
      "text": "Clover",
      "votes": 3
    }
  ],
  "total": 22,
  "multiple": false,
  "endsAt": 1758710400000,
  "running": true,
  "resultsVisible": true,
  "myVotes": [
    0
  ]
}

`PollOption`

إجابة واحدة في استطلاع.

الحقل	النوع	المعنى
`text`	`string`	الإجابة.
`votes`	`integer`أو null	أصواتها (`null` ما دامت النتائج محجوبة).

مثال

{
  "text": "Lavender",
  "votes": 12
}

`ProfileBrief`

ملف شخصي كما يظهر داخل كائنات أخرى: كمؤلف أو في بحث.

الحقل	النوع	المعنى
`id`	`string`	معرّف الحساب: ما يتوقعه `/relations` و`/conversations/{with}`.
`handle`	`string`	الاسم المختصر، دون `@`.
`name`	`string`	الاسم الظاهر. قد يحتوي رموزًا تعبيرية، بما فيها `:name:`.
`verified`	`boolean`	هل الحساب موثَّق.
`accountKind`	`string`	نوع الحساب. `person` — شخص. `business` — منشأة تجارية. `association` — نادٍ أو جمعية. `automated` — حساب آلي، مثل بوت.

مثال

{
  "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "handle": "mara",
  "name": "Mara 🌻",
  "verified": true,
  "accountKind": "person"
}

`Profile`

ملف شخصي بذاته، مع وصفه ومتابعيه.

كل حقول ProfileBrief، وإضافة إلى ذلك:

الحقل	النوع	المعنى
`about`	`string`أو null	الوصف (`null` إن لم يوجد).
`website`	`string`أو null	موقع الملف الشخصي (`null` إن لم يوجد). منذ 2.3.
`websiteVerified`	`boolean`	هل يرتبط الموقع بهذا الملف الشخصي عبر `rel=me`، يُتحقق منه أسبوعيًا. منذ 2.3.
`followers`	`integer`	كم حسابًا يتابعه.
`createdAt`	`integer`أو null	متى أُنشئ الحساب (`null` ما دام العضو يخفي تاريخ الانضمام؛ منذ 2.9).

مثال

{
  "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "handle": "mara",
  "name": "Mara 🌻",
  "verified": true,
  "accountKind": "person",
  "about": "Beekeeper, allotment, too many seeds. :tellmelo:",
  "website": "https://mara-imkerei.example/",
  "websiteVerified": true,
  "followers": 148,
  "createdAt": 1750848000000
}

`CommunityBrief`

المجموعة التي كُتب فيها المنشور.

الحقل	النوع	المعنى
`id`	`string`	معرّف المجموعة.
`name`	`string`أو null	اسمها.

مثال

{
  "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
  "name": "Urban Gardening"
}

`Community`

مجموعة على هذا الخادم.

الحقل	النوع	المعنى
`id`	`string`	معرّف المجموعة.
`name`	`string`	اسمها.
`description`	`string`أو null	الوصف (`null` إن لم يوجد).
`tags`	`string[]`	المواضيع التي تتناولها.
`members`	`integer`	كم عضوًا فيها.
`joinPolicy`	`string`	كيف يُدخل إليها. `open` — يمكن لأي أحد الانضمام. `application` — الانضمام يتطلب طلبًا تقبله المجموعة. `invite` — بالدعوة فقط.
`visibility`	`string`	دائمًا `open` عبر المفتاح. `open` — مرئية للجميع.

مثال

{
  "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
  "name": "Urban Gardening",
  "description": "Balconies, allotments, rooftops: whatever grows.",
  "tags": [
    "garden",
    "bees"
  ],
  "members": 312,
  "joinPolicy": "open",
  "visibility": "open"
}

`Tag`

وسم وعدد المنشورات التي تحمله.

الحقل	النوع	المعنى
`tag`	`string`	الوسم، دون `#`.
`posts`	`integer`	كم منشورًا حديثًا يحمله.

مثال

{
  "tag": "garden",
  "posts": 58
}

`SearchResult`

ثلاث قوائم، قد تكون فارغة.

الحقل	النوع	المعنى
`posts`	`Post[]`	المنشورات المطابقة، الأحدث أولًا.
`profiles`	`ProfileBrief[]`	الملفات الشخصية المطابقة، بحسب الاسم المختصر.
`tags`	`Tag[]`	الوسوم المطابقة، الأكثر استخدامًا أولًا.

مثال

{
  "posts": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "profiles": [
    {
      "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "handle": "mara",
      "name": "Mara 🌻",
      "verified": true,
      "accountKind": "person"
    }
  ],
  "tags": [
    {
      "tag": "garden",
      "posts": 58
    }
  ]
}

`Emoji`

رمز تعبيري لهذا الخادم.

الحقل	النوع	المعنى
`name`	`string`	الاسم، كما يقع بين النقطتين.
`url`	`string`	عنوان الصورة، نسبةً إلى هذا الخادم.

مثال

{
  "name": "tellmelo",
  "url": "/api/media?id=e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b"
}

`Notification`

إشعار. يمكن للسطر الواحد أن يجمع عدة أحداث من النوع نفسه.

الحقل	النوع	المعنى
`id`	`string`	معرّف الإشعار.
`kind`	`string`	ما الذي حدث. `reply` — ردّ عليك أحدهم. `like` — أُعجب أحدهم بمنشورك. `reply_like` — أُعجب أحدهم بردّك. `repost` — أعاد أحدهم نشر منشورك. `follow` — يتابعك أحدهم. `mention` — أشار إليك أحدهم. `group_mention` — أشار أحدهم إلى مجموعة تقودها؛ `text` هو اسمها. `message` — أرسل إليك أحدهم رسالة. `scheduled` — نُشر أحد منشوراتك المجدولة. `reminder` — حان موعد تذكير عن منشور محفوظ. `report` — ما آل إليه بلاغ أرسلته. `moderation` — قرار بشأن حسابك: تحذير أو تقييد أو اعتراض. `team` — عمل جديد للفريق (للمالكين والمديرين والمشرفين فقط). `reward` — مكافأة الدعوة على وشك الانتهاء أو انتهت. `gift` — هدية من الفريق: اشتراك، أو شرارات لك أو لمجموعة تقودها. `present` — هدية من عضو: شرارات أو مدة اشتراك؛ العضو هو `actor`. `spark` — الشرارات تنتهي قريبًا، أو بلغت مجموعة تقودها مستوى أو لن تحتفظ به إلا لفترة. `loyalty` — عن إيقاع الوفاء: يُحتسب أسبوع نشط أو ينقصه يوم، أو مكافأة جديدة أو توشك على الزوال. `impact` — كيف كانت منشوراتك خلال اثنتي عشرة ساعة بعد يوم، في إشعار واحد. `discovery` — دعوة إلى برنامج «مُكتشَف»، أو أن مكانًا فيه يبدأ أو ينتهي. `group_post` — منشور جديد في مجموعة يرنّ جرسها لذلك. `group_moderation` — أزالت قيادة مجموعة أحد منشوراتك، أو أزالتك من المجموعة.
`text`	`string`أو null	للبلاغات والإشراف فقط: النص المتعلق، وإلا `null`.
`actor`	`Actor`	من فعل ذلك.
`postId`	`string`أو null	المنشور المعني (`null` إن لم يتعلق بأي منشور).
`read`	`boolean`	هل عُلّم كمقروء.
`more`	`integer`	كم حدثًا آخر يمثله هذا السطر، فوق الحدث المذكور.
`createdAt`	`integer`	متى حدث أول مرة.
`updatedAt`	`integer`	متى جمع حدثًا آخر آخر مرة. القائمة مرتّبة بحسبه.

مثال

{
  "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
  "kind": "like",
  "text": null,
  "actor": {
    "handle": "jon",
    "name": "Jon"
  },
  "postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "read": false,
  "more": 2,
  "createdAt": 1758624300000,
  "updatedAt": 1758624900000
}

`Actor`

من أطلق الإشعار.

الحقل	النوع	المعنى
`handle`	`string`	الاسم المختصر.
`name`	`string`	الاسم الظاهر.

مثال

{
  "handle": "jon",
  "name": "Jon"
}

`Conversation`

سطر واحد من صندوق رسائلك.

الحقل	النوع	المعنى
`with`	`string`	معرّف الحساب الآخر: ما يتوقعه `/conversations/{with}/messages`.
`handle`	`string`	اسمه المختصر.
`name`	`string`	اسمه الظاهر.
`excerpt`	`string`أو null	بداية آخر رسالة (`null` إن لم يكن فيها نص).
`truncated`	`boolean`	هل قُصّ المقتطف.
`fromMe`	`boolean`	هل آخر رسالة منك.
`lastMessageId`	`string`	معرّف آخر رسالة.
`unread`	`integer`	كم من رسائله لم تقرأها بعد.
`updatedAt`	`integer`	متى كُتبت آخر رسالة.

مثال

{
  "with": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
  "handle": "jon",
  "name": "Jon",
  "excerpt": "See you on Saturday at the market!",
  "truncated": false,
  "fromMe": true,
  "lastMessageId": "7c6b5a49-3827-4165-9f0e-d1c2b3a49586",
  "unread": 0,
  "updatedAt": 1758624060000
}

`Message`

رسالة في محادثة.

الحقل	النوع	المعنى
`id`	`string`	معرّف الرسالة.
`text`	`string`أو null	النص (`null` لرسالة هي صور فقط).
`from`	`string`	معرّف الحساب الذي كتبها.
`to`	`string`	معرّف الحساب الذي كُتبت إليه.
`read`	`boolean`	هل قرأها المستلم.
`media`	`Media[]`	صورها؛ فارغة إن لم توجد.
`replyTo`	`string`أو null	`id` الرسالة التي تجيب عنها هذه الرسالة (`null` إن لم تجب عن أي رسالة). منذ 2.2.
`createdAt`	`integer`	متى أُرسلت.

مثال

{
  "id": "7c6b5a49-3827-4165-9f0e-d1c2b3a49586",
  "text": "See you on Saturday at the market!",
  "from": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "to": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
  "read": true,
  "media": [],
  "replyTo": null,
  "createdAt": 1758624060000
}

`Created`

رد عملية كتابة أنشأت شيئًا.

الحقل	النوع	المعنى
`id`	`string`	معرّف ما أُنشئ.
`scheduledFor`	`integer`أو null	متى يظهر، إن كان النشر مجدولًا (وإلا `null`).
`deleteAt`	`integer`أو null	متى يحذف نفسه، إن ضُبط ذلك (وإلا `null`).

مثال

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "scheduledFor": null,
  "deleteAt": null
}

`Ok`

رد عملية كتابة ليس لديها ما تعيده.

الحقل	النوع	المعنى
`ok`	`boolean`	دائمًا `true`.

مثال

{
  "ok": true
}

الوصف المقروء آليًا

الجدول الذي تقوم عليه هذه الصفحة متاح بصيغة OpenAPI على /api/v2/openapi.json.

https://tellmelo.com/api/v2/openapi.json

ما نتوقعه

تسري القواعد نفسها كما في كل مكان: لا تحرّش، ولا رسائل مزعجة، ولا محتوى لا تملك حقوقه. أنت مسؤول عمّا ينشره مفتاحك.

API

نظرة عامة

بداية سريعة

جرّبه

مفتاحك

ما يمكن للمفتاح فعله

ما لا يستطيعه أي مفتاح

الطلبات والردود

الصفحات

الجديد فقط

الحدود

الترويسات

ما ترسله

ما يعود

عندما لا ينجح شيء

الإصدارات

نقاط النهاية

المدخل

GET/api/v2

مثال على الطلب

الرد

المنشورات

GET/api/v2/posts

المعاملات

مثال على الطلب

الرد

GET/api/v2/posts/{id}

المعاملات

مثال على الطلب

الرد

POST/api/v2/posts

المعاملات

مثال على الطلب

الرد

DELETE/api/v2/posts/{id}

المعاملات

مثال على الطلب

الرد

الردود

GET/api/v2/posts/{id}/replies

المعاملات

مثال على الطلب

الرد

POST/api/v2/posts/{id}/replies

المعاملات

مثال على الطلب

الرد

الاستطلاعات

POST/api/v2/posts/{id}/vote

المعاملات

مثال على الطلب

الرد

الملفات الشخصية

GET/api/v2/profiles/{handle}

المعاملات

مثال على الطلب

الرد

GET/api/v2/profiles/{handle}/posts

المعاملات

مثال على الطلب

الرد

المجموعات

GET/api/v2/communities

المعاملات

مثال على الطلب

الرد

GET/api/v2/communities/{id}

المعاملات

مثال على الطلب

الرد

GET/api/v2/communities/{id}/posts

المعاملات

مثال على الطلب

الرد

استكشاف

GET/api/v2/tags

المعاملات

مثال على الطلب

الرد

GET/api/v2/search

GET`/api/v2`

GET`/api/v2/posts`

GET`/api/v2/posts/{id}`

POST`/api/v2/posts`

DELETE`/api/v2/posts/{id}`

GET`/api/v2/posts/{id}/replies`

POST`/api/v2/posts/{id}/replies`

POST`/api/v2/posts/{id}/vote`

GET`/api/v2/profiles/{handle}`

GET`/api/v2/profiles/{handle}/posts`

GET`/api/v2/communities`

GET`/api/v2/communities/{id}`

GET`/api/v2/communities/{id}/posts`

GET`/api/v2/tags`

GET`/api/v2/search`

GET`/api/v2/emojis`

GET`/api/v2/me`

GET`/api/v2/feed`

GET`/api/v2/notifications`

POST`/api/v2/notifications/read`

GET`/api/v2/conversations`

GET`/api/v2/conversations/{with}/messages`

POST`/api/v2/conversations/{with}/messages`

POST`/api/v2/conversations/{with}/read`

POST`/api/v2/relations`

`Service`

`RateLimit`

`Post`

`Reply`

`Counts`

`Media`

`Poll`

`PollOption`

`ProfileBrief`

`Profile`

`CommunityBrief`

`Community`

`Tag`

`SearchResult`

`Emoji`

`Notification`

`Actor`

`Conversation`

`Message`

`Created`

`Ok`