wWaslapractice API

Wasla API

Wasla is a practice professional network. Its REST API behaves like a real product's API, so you can learn to connect any API to n8n without paying for anything.

Base URLhttps://api.abdallahhelal.cloud/api/v1
FormatJSON in, JSON out (UTF-8)
AuthAPI key, see Authentication
Limit60 requests per minute

Everything you create (posts, messages, requests, webhooks) lives in your own sandbox. Other students never see it. The 150 people, 25 companies and 80 jobs are fictional and the same for everyone.

Create an account and the examples on this page will contain your own key.

Quickstart

  1. Get your key. It is on your Developer page.
  2. Make your first request. Run this in a terminal:
    curl "https://api.abdallahhelal.cloud/api/v1/me" \
      -H "X-API-Key: YOUR_API_KEY"
  3. Do the same in n8n. Add an HTTP Request node, click Import cURL, paste the command above, then press Execute step.
  4. Move the key into a credential. In the node, set Authentication = Generic Credential Type, Generic Auth Type = Header Auth, Name = X-API-Key, Value = your key. Delete the header that Import cURL added. Now you can share the workflow without leaking your key.
  5. Try a request that changes something.
    curl -X POST "https://api.abdallahhelal.cloud/api/v1/posts" \
      -H "X-API-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"text":"My first post from n8n!"}'
    Open your feed: the post is there. Wait a few seconds: someone likes it.

Authentication

Every endpoint except /health needs your API key. You can send the same key in three ways. Real APIs usually pick one, and their docs tell you which. Wasla accepts all three so you can see the difference.

Where the key goesExamplen8n credential
Header (recommended)X-API-Key: YOUR_API_KEYHeader Auth: Name X-API-Key, Value = key
Bearer tokenAuthorization: Bearer YOUR_API_KEYBearer Auth, or Header Auth with Name Authorization and Value Bearer <key>
Query string (works, not recommended)?api_key=YOUR_API_KEYQuery Auth: Name api_key, Value = key

If you send more than one, the header wins, then Bearer, then the query. Your request log shows which one each call used.

Keys in the URL end up in logs, browser history and screenshots, and inside the workflow if you share it. Prefer a header and an n8n credential. If a key leaks, regenerate it on the Developer page: the old one stops working at once.

curl "https://api.abdallahhelal.cloud/api/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.abdallahhelal.cloud/api/v1/me?api_key=YOUR_API_KEY"

No key: 401 missing_api_key. Wrong or regenerated key: 401 invalid_api_key.

Requests and responses

  • Send bodies as JSON with Content-Type: application/json. Other content types get 415. The only exception is the avatar upload (multipart/form-data).
  • Unknown fields are refused with 422, and the message suggests the right name: sending txt instead of text answers Did you mean "text"?
  • Numbers can be sent as numbers or numeric strings (3 or "3"), because n8n fields often send strings.
  • Times are ISO 8601 in UTC, like 2026-11-21T10:00:00.000Z.
  • Post ids are strings: post_12 for yours, seed_3 for other people's. Use them exactly as returned.
  • Successful creates answer 201, async jobs 202, deletes 204 with an empty body.

Errors

Every error has the same JSON shape. Read the status code first, then error.code and error.message. details lists the fields or parameters that were wrong.

{
  "error": {
    "status": 422,
    "code": "validation_failed",
    "message": "\"text\" is required.",
    "details": [
      {
        "field": "text",
        "message": "\"text\" is required."
      }
    ],
    "docs_url": "https://api.abdallahhelal.cloud/docs#errors"
  }
}
StatuscodeWhat it means
400malformed_jsonThe body is not valid JSON (a missing quote or bracket).
400json_must_be_objectThe body is JSON, but an array or a single value instead of an object.
400invalid_parameterA query parameter has the wrong type or value (for example per_page=abc).
400invalid_idAn id in the URL has the wrong format (post ids look like post_12 or seed_3).
401missing_api_keyNo API key was sent.
401invalid_api_keyThe key is wrong, or it was regenerated.
403forbiddenYour key is fine, but you cannot do this (for example edit someone else's post).
404not_foundThere is no endpoint at this path. Check the URL.
404*_not_foundThe item does not exist in your sandbox: person_not_found, company_not_found, job_not_found, post_not_found, application_not_found, request_not_found, export_not_found, webhook_not_found, like_not_found, unknown_simulation.
405method_not_allowedThe path exists, but not with this method. The Allow header lists the right ones.
409already_applied / already_likedYou already did this.
409already_connected / request_pending / request_not_pendingThe connection request is in the wrong state for this action.
409export_not_ready / no_posts / no_applicationsSomething has to happen first.
413payload_too_large / file_too_largeThe body is over 100 KB, or the image is over 2 MB.
415unsupported_media_typeWrong Content-Type. JSON endpoints need application/json, the avatar upload needs multipart/form-data.
415unsupported_file_typeThe avatar is not a PNG, JPEG or WEBP image.
422validation_failedA field is missing, too long, or not allowed. details[] says which one.
422limit_reachedYou hit a sandbox limit (500 posts, 20 webhooks).
422webhook_url_not_allowed / webhook_url_unresolvableThe webhook URL is not public, not http(s), or the host does not exist.
429rate_limit_exceededMore than 60 requests in one minute. Wait for Retry-After seconds.
500internal_errorSomething broke on our side. Not your fault.
503temporarily_unavailableOnly from GET /test/flaky, on purpose.

Seeing errors in n8n

  • By default the HTTP Request node stops on any 4xx or 5xx. To see the status code and headers, open Options and add Response, then turn on Include Response Headers and Status.
  • To keep the workflow running after an error, set the node Settings tab, On Error = Continue (or Continue using error output).
  • Practice with GET /test/status/{code} and GET /test/flaky.

Rate limits

Each key can make 60 requests per minute. Every answer tells you where you stand:

X-RateLimit-LimitRequests allowed per minute.
X-RateLimit-RemainingRequests left in this minute.
X-RateLimit-ResetUnix time (seconds) when the counter resets.
Retry-AfterOnly on 429: seconds to wait.

Over the limit you get 429 rate_limit_exceeded. In n8n, when one node runs for many items: open Options, add Batching, set Items per Batch = 1 and Batch Interval = 1100 ms. Or turn on Retry On Fail in Settings with a wait of a few seconds.

Pagination

Lists return 10 items by default (per_page up to 50). Ask for more pages with page.

curl "https://api.abdallahhelal.cloud/api/v1/people?per_page=50&page=2" \
  -H "X-API-Key: YOUR_API_KEY"
{
  "data": [
    "...50 people..."
  ],
  "pagination": {
    "page": 2,
    "per_page": 50,
    "total": 150,
    "total_pages": 3,
    "has_more": true,
    "next_url": "https://api.abdallahhelal.cloud/api/v1/people?page=3&per_page=50"
  }
}

There is also a Link: <next_url>; rel="next" header. On the last page has_more is false and next_url is null.

Get every page in n8n

HTTP Request node, Options, add Pagination. Pick one of these:

SettingWay 1: update a parameterWay 2: next URL
Pagination ModeUpdate a Parameter in Each RequestResponse Contains Next URL
Parameter / Next URLType Query, Name page, Value {{ $pageCount + 1 }}Next URL {{ $response.body.pagination.next_url }}
Pagination Complete WhenOther: {{ $response.body.pagination.has_more === false }}Other: {{ !$response.body.pagination.next_url }}

next_url never contains your key. Use a credential (Header Auth) so n8n adds the key to every page.

Polling (async jobs)

Some work takes time. POST /exports answers at once with 202 and status: "processing". You then ask again every few seconds until it says completed. That loop is called polling.

HTTP Request  POST /exports
      |
     Wait 5 seconds   <---------------------+
      |                                     |
HTTP Request  GET {{ $json.check_url }}     |
      |                                     |
      IF status = "completed" -- false -----+
      | true
HTTP Request  GET {{ $json.download_url }}  (Response Format: File)

Tip: inside the loop, refer to the first node by name, for example {{ $('Start export').item.json.check_url }}, because $json changes after the Wait node.

Webhooks guide

With the API, you ask Wasla for data. With a webhook, Wasla tells you the moment something happens, by sending a POST request to your URL.

Set it up with n8n

  1. Add a Webhook node. Set HTTP Method = POST. Copy its Test URL.
  2. On your Developer page paste the URL, tick the events you want, press Add webhook. (Or POST /webhooks.)
  3. In n8n press Listen for test event, then press Send test on the Developer page. The ping event appears in n8n.
  4. When the workflow is ready, activate it and switch the URL to the Production URL.

Wasla can only call public URLs. localhost, 127.0.0.1 and private network addresses are refused with 422 webhook_url_not_allowed. If your n8n runs on your laptop, use n8n Cloud or a tunnel.

Events

EventWhendata contains
post.createdYou create a post (API or website).post
post.commentedA fake person comments on your post, about 8 s after you post.post, comment
post.likedA fake person likes your post, about 4 s after you post.post, liked_by
connection.requestedA fake person sends you a connection request (press the button on the Developer page, or POST /simulate/incoming_request).request
connection.acceptedThe person you asked accepts, about 6 s after your request.request
message.receivedThe person you messaged replies, about 5 s later.message
application.status_changedYour job application moves: submitted -> viewed -> interview, about 20 s per step.application, previous_status
export.completedAn export you started is ready, about 15 s later.export
pingYou press Send test (or POST /webhooks/{id}/test). Always sent, whatever events you picked.message, webhook_id

What arrives

POST /webhook/abc123
Content-Type: application/json
User-Agent: Wasla-Webhooks/1.0
X-Wasla-Event: message.received
X-Wasla-Delivery: dlv_88
X-Wasla-Timestamp: 1795269600
X-Wasla-Signature: sha256=5d1c0f...

{
  "id": "evt_120",
  "type": "message.received",
  "created_at": "2026-11-21T10:00:05.000Z",
  "data": {
    "message": {
      "id": 32,
      "person": {
        "id": 12,
        "name": "Sherif Nasser",
        "...": "..."
      },
      "sender": "them",
      "text": "Yes! Send me your CV.",
      "read": false,
      "created_at": "2026-11-21T10:00:05.000Z"
    }
  }
}

In n8n the JSON is under {{ $json.body }}, for example {{ $json.body.data.message.text }}, and the headers under {{ $json.headers }}.

Retries and the delivery log

  • A delivery succeeds when your server answers 2xx within 10 seconds. Redirects are not followed and count as failures.
  • Failed deliveries are retried after 10 seconds and again after 60 seconds (3 attempts in total).
  • After 20 failures in a row the endpoint is turned off. Fix it and turn it back on.
  • Every attempt is in the delivery log, with the status code, the time taken and the start of your server's answer.
  • In the n8n Webhook node, keep Respond = Immediately so the answer is fast.

Check the signature (optional, recommended)

Anyone who knows your webhook URL could send fake events. The signature proves the request came from Wasla. It is an HMAC SHA-256 of timestamp + "." + raw body, using your endpoint's secret. In an n8n Code node:

const crypto = require('crypto');
const secret = 'whsec_...';                       // your endpoint's signing secret
const ts = $json.headers['x-wasla-timestamp'];
const body = JSON.stringify($json.body);          // same as the raw body Wasla sent
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(ts + '.' + body).digest('hex');
return [{ json: { valid: expected === $json.headers['x-wasla-signature'] } }];

If your n8n blocks require('crypto') in the Code node, use the Crypto node (Action: Hmac, Type: SHA256, Encoding: HEX) on the same text.

Your account

GET /me

Your own profile. The easiest request to test your key.

curl "https://api.abdallahhelal.cloud/api/v1/me" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "id": 1,
  "name": "Your Name",
  "email": "you@example.com",
  "headline": "Automation builder",
  "about": "",
  "city": "Cairo",
  "avatar_url": null,
  "connections_count": 4,
  "created_at": "2026-11-21T09:00:00.000Z"
}

PATCH /me

Change your headline, about text or city. Send only the fields you want to change.

NameInTypeRequiredDescription
headlinebodystringoptionalUp to 120 characters.
aboutbodystringoptionalUp to 2000 characters.
citybodystringoptionalUp to 60 characters.
curl -X PATCH "https://api.abdallahhelal.cloud/api/v1/me" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"headline":"Automation builder","city":"Cairo"}'

Response 200

{
  "id": 1,
  "name": "Your Name",
  "email": "you@example.com",
  "headline": "Automation builder",
  "about": "",
  "city": "Cairo",
  "avatar_url": null,
  "connections_count": 4,
  "created_at": "2026-11-21T09:00:00.000Z"
}

Errors: validation_failed

POST /me/avatar

Upload a profile photo as multipart/form-data with a field named file. PNG, JPEG or WEBP, up to 2 MB. In n8n: Body Content Type = Form-Data, parameter type n8n Binary File, name file, input data field data.

Response 200

{
  "id": 1,
  "name": "Your Name",
  "email": "you@example.com",
  "headline": "Automation builder",
  "about": "",
  "city": "Cairo",
  "avatar_url": "https://api.abdallahhelal.cloud/avatars/1",
  "connections_count": 4,
  "created_at": "2026-11-21T09:00:00.000Z"
}

Errors: unsupported_media_type unsupported_file_type file_too_large validation_failed

DELETE /me/avatar

Remove your photo. Returns 204 No Content (an empty body).

curl -X DELETE "https://api.abdallahhelal.cloud/api/v1/me/avatar" \
  -H "X-API-Key: YOUR_API_KEY"

People

GET /people

150 fictional professionals. Paginated.

NameInTypeRequiredDescription
searchquerystringoptionalMatches the name, the Arabic name or the headline.
titlequerystringoptionalPart of the job title, e.g. Engineer.
cityquerystringoptionalExact city, e.g. Cairo, Dubai.
company_idqueryintegeroptionalOnly people at this company.
open_to_workquerybooleanoptionaltrue to see people looking for work.
pagequeryintegeroptionalDefault 1.
per_pagequeryintegeroptionalDefault 10, max 50.
curl "https://api.abdallahhelal.cloud/api/v1/people?city=Cairo&per_page=5" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "id": 3,
      "name": "Mohamed Abdelrahman",
      "name_ar": "محمد عبد الرحمن",
      "title": "Senior Graphic Designer",
      "headline": "Senior Graphic Designer at Masr Data Labs",
      "company": {
        "id": 10,
        "name": "Masr Data Labs"
      },
      "city": "Jeddah",
      "about": "I build systems that remove boring work. Coffee, clean data and clear docs.",
      "skills": [
        "Figma",
        "Motion",
        "Illustrator",
        "Social media"
      ],
      "open_to_work": false,
      "avatar_color": "#55606b",
      "connection_status": "none",
      "profile_url": "https://api.abdallahhelal.cloud/people/3"
    },
    "..."
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 150,
    "total_pages": 15,
    "has_more": true,
    "next_url": "https://api.abdallahhelal.cloud/api/v1/people?page=2&per_page=10"
  }
}

Errors: invalid_parameter

GET /people/{id}

One person. connection_status is none, pending_outgoing, pending_incoming or connected.

curl "https://api.abdallahhelal.cloud/api/v1/people/1" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "id": 3,
  "name": "Mohamed Abdelrahman",
  "name_ar": "محمد عبد الرحمن",
  "title": "Senior Graphic Designer",
  "headline": "Senior Graphic Designer at Masr Data Labs",
  "company": {
    "id": 10,
    "name": "Masr Data Labs"
  },
  "city": "Jeddah",
  "about": "I build systems that remove boring work. Coffee, clean data and clear docs.",
  "skills": [
    "Figma",
    "Motion",
    "Illustrator",
    "Social media"
  ],
  "open_to_work": false,
  "avatar_color": "#55606b",
  "connection_status": "none",
  "profile_url": "https://api.abdallahhelal.cloud/people/3"
}

Errors: invalid_id person_not_found

Companies

GET /companies

25 fictional companies. Paginated.

NameInTypeRequiredDescription
searchquerystringoptionalPart of the name.
industryquerystringoptionalExact industry, e.g. Software.
curl "https://api.abdallahhelal.cloud/api/v1/companies" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "id": 2,
      "name": "Cairo Cloudworks",
      "industry": "Software",
      "city": "Cairo",
      "size": "51-200",
      "website": "https://cairocloudworks.example",
      "about": "Cairo Cloudworks is a fictional software company based in Cairo. It exists only inside Wasla for practice.",
      "employees_count": 5,
      "open_jobs_count": 2
    },
    "..."
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 150,
    "total_pages": 15,
    "has_more": true,
    "next_url": "https://api.abdallahhelal.cloud/api/v1/people?page=2&per_page=10"
  }
}

GET /companies/{id}

One company with its employee and job counts.

curl "https://api.abdallahhelal.cloud/api/v1/companies/1" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "id": 2,
  "name": "Cairo Cloudworks",
  "industry": "Software",
  "city": "Cairo",
  "size": "51-200",
  "website": "https://cairocloudworks.example",
  "about": "Cairo Cloudworks is a fictional software company based in Cairo. It exists only inside Wasla for practice.",
  "employees_count": 5,
  "open_jobs_count": 2
}

Errors: company_not_found

Jobs and applications

GET /jobs

80 jobs, newest first. Paginated.

NameInTypeRequiredDescription
qquerystringoptionalKeyword in the title or description.
cityquerystringoptionalCity, or Remote.
typequerystringoptionalfull_time, part_time, contract or internship.
remotequerybooleanoptionaltrue or false.
company_idqueryintegeroptionalOnly this company.
curl "https://api.abdallahhelal.cloud/api/v1/jobs?remote=true&type=full_time" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "id": 1,
      "title": "Lead Marketing Specialist",
      "company": {
        "id": 20,
        "name": "Sinai Solar"
      },
      "city": "Remote",
      "type": "internship",
      "remote": true,
      "salary_range": "EGP 9,750 / month",
      "description": "Sinai Solar is looking for a Lead Marketing Specialist to join the team (remote friendly). You will work with real customers, ship small improvements every week and automate the boring parts of the job.",
      "requirements": [
        "Experience with SEO",
        "Experience with Content",
        "Experience with Meta Ads",
        "Arabic and English"
      ],
      "posted_at": "2026-11-10T00:27:54.505Z",
      "applied": false,
      "url": "https://api.abdallahhelal.cloud/jobs/1"
    },
    "..."
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 150,
    "total_pages": 15,
    "has_more": true,
    "next_url": "https://api.abdallahhelal.cloud/api/v1/people?page=2&per_page=10"
  }
}

Errors: invalid_parameter

GET /jobs/{id}

One job. applied tells you if you already applied.

curl "https://api.abdallahhelal.cloud/api/v1/jobs/1" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "id": 1,
  "title": "Lead Marketing Specialist",
  "company": {
    "id": 20,
    "name": "Sinai Solar"
  },
  "city": "Remote",
  "type": "internship",
  "remote": true,
  "salary_range": "EGP 9,750 / month",
  "description": "Sinai Solar is looking for a Lead Marketing Specialist to join the team (remote friendly). You will work with real customers, ship small improvements every week and automate the boring parts of the job.",
  "requirements": [
    "Experience with SEO",
    "Experience with Content",
    "Experience with Meta Ads",
    "Arabic and English"
  ],
  "posted_at": "2026-11-10T00:27:54.505Z",
  "applied": false,
  "url": "https://api.abdallahhelal.cloud/jobs/1"
}

Errors: job_not_found

POST /jobs/{id}/applications

Apply to a job. Its status then moves from submitted to viewed to interview (about 20 seconds per step), and each move fires application.status_changed.

NameInTypeRequiredDescription
cover_notebodystringoptionalUp to 2000 characters.
resume_urlbodystringoptionalA full http(s) link.
curl -X POST "https://api.abdallahhelal.cloud/api/v1/jobs/1/applications" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cover_note":"Applying from n8n","resume_url":"https://example.com/cv.pdf"}'

Response 201

{
  "id": 5,
  "job": {
    "id": 1,
    "title": "Lead Marketing Specialist",
    "company": {
      "id": 20,
      "name": "Sinai Solar"
    }
  },
  "cover_note": "Applying from n8n",
  "resume_url": "https://example.com/cv.pdf",
  "status": "submitted",
  "created_at": "2026-11-21T10:00:00.000Z",
  "updated_at": "2026-11-21T10:00:00.000Z"
}

Errors: already_applied validation_failed job_not_found

GET /applications

Your applications, newest first. Paginated.

NameInTypeRequiredDescription
statusquerystringoptionalsubmitted, viewed, interview, rejected or offer.
curl "https://api.abdallahhelal.cloud/api/v1/applications" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "id": 5,
      "job": {
        "id": 1,
        "title": "Lead Marketing Specialist",
        "company": {
          "id": 20,
          "name": "Sinai Solar"
        }
      },
      "cover_note": "Applying from n8n",
      "resume_url": "https://example.com/cv.pdf",
      "status": "submitted",
      "created_at": "2026-11-21T10:00:00.000Z",
      "updated_at": "2026-11-21T10:00:00.000Z"
    },
    "..."
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 150,
    "total_pages": 15,
    "has_more": true,
    "next_url": "https://api.abdallahhelal.cloud/api/v1/people?page=2&per_page=10"
  }
}

GET /applications/{id}

One of your applications.

curl "https://api.abdallahhelal.cloud/api/v1/applications/1" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "id": 5,
  "job": {
    "id": 1,
    "title": "Lead Marketing Specialist",
    "company": {
      "id": 20,
      "name": "Sinai Solar"
    }
  },
  "cover_note": "Applying from n8n",
  "resume_url": "https://example.com/cv.pdf",
  "status": "submitted",
  "created_at": "2026-11-21T10:00:00.000Z",
  "updated_at": "2026-11-21T10:00:00.000Z"
}

Errors: application_not_found

Posts, comments and likes

GET /posts

Your feed: everyone's posts plus yours, newest first. Ids starting with seed_ are other people's posts, ids starting with post_ are yours.

NameInTypeRequiredDescription
authorquerystringoptionalall (default) or me.
curl "https://api.abdallahhelal.cloud/api/v1/posts" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "id": "post_7",
      "text": "Posted from n8n!",
      "visibility": "public",
      "author": {
        "type": "you",
        "id": 1,
        "name": "Your Name",
        "headline": ""
      },
      "likes_count": 0,
      "comments_count": 0,
      "liked_by_you": false,
      "created_at": "2026-11-21T10:00:00.000Z",
      "updated_at": "2026-11-21T10:00:00.000Z",
      "url": "https://api.abdallahhelal.cloud/feed#post_7"
    },
    "..."
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 150,
    "total_pages": 15,
    "has_more": true,
    "next_url": "https://api.abdallahhelal.cloud/api/v1/people?page=2&per_page=10"
  }
}

POST /posts

Create a post. Fires post.created. A few seconds later a fake person likes it and another comments (more webhooks).

NameInTypeRequiredDescription
textbodystringrequired1 to 3000 characters.
visibilitybodystringoptionalpublic (default) or connections.
curl -X POST "https://api.abdallahhelal.cloud/api/v1/posts" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Posted from n8n!"}'

Response 201

{
  "id": "post_7",
  "text": "Posted from n8n!",
  "visibility": "public",
  "author": {
    "type": "you",
    "id": 1,
    "name": "Your Name",
    "headline": ""
  },
  "likes_count": 0,
  "comments_count": 0,
  "liked_by_you": false,
  "created_at": "2026-11-21T10:00:00.000Z",
  "updated_at": "2026-11-21T10:00:00.000Z",
  "url": "https://api.abdallahhelal.cloud/feed#post_7"
}

Errors: validation_failed limit_reached malformed_json unsupported_media_type

GET /posts/{id}

One post.

curl "https://api.abdallahhelal.cloud/api/v1/posts/seed_1" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "id": "post_7",
  "text": "Posted from n8n!",
  "visibility": "public",
  "author": {
    "type": "you",
    "id": 1,
    "name": "Your Name",
    "headline": ""
  },
  "likes_count": 0,
  "comments_count": 0,
  "liked_by_you": false,
  "created_at": "2026-11-21T10:00:00.000Z",
  "updated_at": "2026-11-21T10:00:00.000Z",
  "url": "https://api.abdallahhelal.cloud/feed#post_7"
}

Errors: invalid_id post_not_found

PATCH /posts/{id}

Edit one of your posts. Use an id you got from POST /posts (the example uses post_7). Editing a seed_ post returns 403.

NameInTypeRequiredDescription
textbodystringoptional1 to 3000 characters.
visibilitybodystringoptionalpublic or connections.
curl -X PATCH "https://api.abdallahhelal.cloud/api/v1/posts/post_7" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Edited from n8n"}'

Response 200

{
  "id": "post_7",
  "text": "Posted from n8n!",
  "visibility": "public",
  "author": {
    "type": "you",
    "id": 1,
    "name": "Your Name",
    "headline": ""
  },
  "likes_count": 0,
  "comments_count": 0,
  "liked_by_you": false,
  "created_at": "2026-11-21T10:00:00.000Z",
  "updated_at": "2026-11-21T10:00:00.000Z",
  "url": "https://api.abdallahhelal.cloud/feed#post_7"
}

Errors: forbidden post_not_found

DELETE /posts/{id}

Delete one of your posts (use your own post id). Returns 204 with an empty body.

curl -X DELETE "https://api.abdallahhelal.cloud/api/v1/posts/post_7" \
  -H "X-API-Key: YOUR_API_KEY"

Errors: forbidden post_not_found

GET /posts/{id}/comments

Comments on a post, oldest first. Paginated.

curl "https://api.abdallahhelal.cloud/api/v1/posts/seed_1/comments" \
  -H "X-API-Key: YOUR_API_KEY"

POST /posts/{id}/comments

Comment on any post.

NameInTypeRequiredDescription
textbodystringrequired1 to 1000 characters.
curl -X POST "https://api.abdallahhelal.cloud/api/v1/posts/seed_1/comments" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Great tip!"}'

Response 201

{
  "id": 14,
  "post_id": "seed_1",
  "text": "Great tip!",
  "author": {
    "type": "you",
    "id": 1,
    "name": "Your Name"
  },
  "created_at": "2026-11-21T10:00:00.000Z"
}

POST /posts/{id}/likes

Like a post.

curl -X POST "https://api.abdallahhelal.cloud/api/v1/posts/seed_1/likes" \
  -H "X-API-Key: YOUR_API_KEY"

Response 201

{
  "post_id": "seed_1",
  "liked_by_you": true,
  "likes_count": 3
}

Errors: already_liked

DELETE /posts/{id}/likes

Remove your like. Returns 204.

curl -X DELETE "https://api.abdallahhelal.cloud/api/v1/posts/seed_1/likes" \
  -H "X-API-Key: YOUR_API_KEY"

Errors: like_not_found

Network

GET /connections

People you are connected with. Paginated.

curl "https://api.abdallahhelal.cloud/api/v1/connections" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "person": {
        "id": 3,
        "name": "Mohamed Abdelrahman",
        "...": "..."
      },
      "connected_at": "2026-11-21T10:00:06.000Z"
    },
    "..."
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 150,
    "total_pages": 15,
    "has_more": true,
    "next_url": "https://api.abdallahhelal.cloud/api/v1/people?page=2&per_page=10"
  }
}

GET /connection-requests

Connection requests. Paginated.

NameInTypeRequiredDescription
directionquerystringoptionalincoming or outgoing.
statusquerystringoptionalpending (default), accepted, declined or all.
curl "https://api.abdallahhelal.cloud/api/v1/connection-requests?direction=incoming" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "id": 9,
      "direction": "outgoing",
      "status": "pending",
      "note": "Hi from n8n!",
      "person": {
        "id": 3,
        "name": "Mohamed Abdelrahman",
        "...": "..."
      },
      "created_at": "2026-11-21T10:00:00.000Z",
      "updated_at": "2026-11-21T10:00:00.000Z"
    },
    "..."
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 150,
    "total_pages": 15,
    "has_more": true,
    "next_url": "https://api.abdallahhelal.cloud/api/v1/people?page=2&per_page=10"
  }
}

POST /connection-requests

Ask someone to connect. They accept about 6 seconds later and connection.accepted fires.

NameInTypeRequiredDescription
person_idbodyintegerrequiredId from /people.
notebodystringoptionalUp to 300 characters.
curl -X POST "https://api.abdallahhelal.cloud/api/v1/connection-requests" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_id":3,"note":"Hi from n8n!"}'

Response 201

{
  "id": 9,
  "direction": "outgoing",
  "status": "pending",
  "note": "Hi from n8n!",
  "person": {
    "id": 3,
    "name": "Mohamed Abdelrahman",
    "...": "..."
  },
  "created_at": "2026-11-21T10:00:00.000Z",
  "updated_at": "2026-11-21T10:00:00.000Z"
}

Errors: already_connected request_pending person_not_found validation_failed

POST /connection-requests/{id}/accept

Accept an incoming pending request.

curl -X POST "https://api.abdallahhelal.cloud/api/v1/connection-requests/1/accept" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "id": 9,
  "direction": "incoming",
  "status": "accepted",
  "note": "Hi from n8n!",
  "person": {
    "id": 3,
    "name": "Mohamed Abdelrahman",
    "...": "..."
  },
  "created_at": "2026-11-21T10:00:00.000Z",
  "updated_at": "2026-11-21T10:00:00.000Z"
}

Errors: request_not_pending request_not_found

POST /connection-requests/{id}/decline

Decline an incoming pending request.

curl -X POST "https://api.abdallahhelal.cloud/api/v1/connection-requests/1/decline" \
  -H "X-API-Key: YOUR_API_KEY"

Errors: request_not_pending request_not_found

Messages

GET /messages

Without parameters: your conversations, newest first, with unread_count. With with=<person id>: one conversation, oldest first (this marks it as read).

NameInTypeRequiredDescription
withqueryintegeroptionalA person id to get one conversation.
curl "https://api.abdallahhelal.cloud/api/v1/messages" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "person": {
        "id": 12,
        "name": "Sherif Nasser",
        "name_ar": "شريف ناصر",
        "headline": "...",
        "avatar_color": "#2c8ba3"
      },
      "last_message": {
        "id": 31,
        "person": {
          "id": 12,
          "name": "Sherif Nasser",
          "name_ar": "شريف ناصر",
          "headline": "...",
          "avatar_color": "#2c8ba3"
        },
        "sender": "them",
        "text": "Yes! Send me your CV.",
        "read": true,
        "created_at": "2026-11-21T10:00:00.000Z"
      },
      "unread_count": 1
    },
    "..."
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 150,
    "total_pages": 15,
    "has_more": true,
    "next_url": "https://api.abdallahhelal.cloud/api/v1/people?page=2&per_page=10"
  }
}

POST /messages

Message someone. They reply about 5 seconds later and message.received fires.

NameInTypeRequiredDescription
tobodyintegerrequiredPerson id.
textbodystringrequired1 to 2000 characters.
curl -X POST "https://api.abdallahhelal.cloud/api/v1/messages" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":12,"text":"Hi! Are you hiring?"}'

Response 201

{
  "id": 31,
  "person": {
    "id": 12,
    "name": "Sherif Nasser",
    "name_ar": "شريف ناصر",
    "headline": "...",
    "avatar_color": "#2c8ba3"
  },
  "sender": "you",
  "text": "Hi! Are you hiring?",
  "read": true,
  "created_at": "2026-11-21T10:00:00.000Z"
}

Errors: validation_failed person_not_found

Exports (async)

POST /exports

Start a CSV export of your connections. It answers at once with 202 Accepted and status processing. The file is ready about 15 seconds later. See Polling.

curl -X POST "https://api.abdallahhelal.cloud/api/v1/exports" \
  -H "X-API-Key: YOUR_API_KEY"

Response 202

{
  "id": 3,
  "status": "processing",
  "created_at": "2026-11-21T10:00:00.000Z",
  "completed_at": null,
  "check_url": "https://api.abdallahhelal.cloud/api/v1/exports/3",
  "download_url": null,
  "message": "Your export started. Check check_url every few seconds until status is \"completed\"."
}

GET /exports/{id}

Check an export. When status is completed, download_url is filled.

curl "https://api.abdallahhelal.cloud/api/v1/exports/1" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "id": 3,
  "status": "completed",
  "created_at": "2026-11-21T10:00:00.000Z",
  "completed_at": "2026-11-21T10:00:15.000Z",
  "check_url": "https://api.abdallahhelal.cloud/api/v1/exports/3",
  "download_url": "https://api.abdallahhelal.cloud/api/v1/exports/3/download"
}

Errors: export_not_found

GET /exports/{id}/download

The CSV file (text/csv). 409 while it is still processing.

curl "https://api.abdallahhelal.cloud/api/v1/exports/1/download" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

person_id,name,title,company,city,connected_at
3,Omar Saleh,Automation Engineer,Cairo Cloudworks,Cairo,2026-11-21T10:00:06.000Z

Errors: export_not_ready

Webhooks

GET /webhooks

Your webhook endpoints. Secrets are masked.

curl "https://api.abdallahhelal.cloud/api/v1/webhooks" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "id": 2,
      "url": "https://your-n8n.example.com/webhook/abc123",
      "events": [
        "post.created",
        "message.received"
      ],
      "description": "n8n demo",
      "enabled": true,
      "secret": "whsec_3kF9...(shown in full only when created)",
      "fail_count": 0,
      "disabled_reason": null,
      "last_delivery": null,
      "created_at": "2026-11-21T10:00:00.000Z"
    },
    "..."
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 150,
    "total_pages": 15,
    "has_more": true,
    "next_url": "https://api.abdallahhelal.cloud/api/v1/people?page=2&per_page=10"
  }
}

POST /webhooks

Register a URL. The full secret is returned here (and on your Developer page). Use "*" for all events.

NameInTypeRequiredDescription
urlbodystringrequiredA public http(s) URL, like your n8n Production URL.
eventsbodyarrayrequiredOne or more of: post.created, post.commented, post.liked, connection.requested, connection.accepted, message.received, application.status_changed, export.completed, or "*".
descriptionbodystringoptionalUp to 200 characters.
curl -X POST "https://api.abdallahhelal.cloud/api/v1/webhooks" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-n8n.example.com/webhook/abc123","events":["post.created","message.received"]}'

Response 201

{
  "id": 2,
  "url": "https://your-n8n.example.com/webhook/abc123",
  "events": [
    "post.created",
    "message.received"
  ],
  "description": "n8n demo",
  "enabled": true,
  "secret": "whsec_3kF9...(shown in full only when created)",
  "fail_count": 0,
  "disabled_reason": null,
  "last_delivery": null,
  "created_at": "2026-11-21T10:00:00.000Z"
}

Errors: webhook_url_not_allowed validation_failed limit_reached

GET /webhooks/{id}

One endpoint, with fail_count and its last delivery.

curl "https://api.abdallahhelal.cloud/api/v1/webhooks/1" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "id": 2,
  "url": "https://your-n8n.example.com/webhook/abc123",
  "events": [
    "post.created",
    "message.received"
  ],
  "description": "n8n demo",
  "enabled": true,
  "secret": "whsec_3kF9...(shown in full only when created)",
  "fail_count": 0,
  "disabled_reason": null,
  "last_delivery": null,
  "created_at": "2026-11-21T10:00:00.000Z"
}

Errors: webhook_not_found

PATCH /webhooks/{id}

Change the URL, events or description, or set enabled. Turning it back on resets fail_count.

NameInTypeRequiredDescription
urlbodystringoptional
eventsbodyarrayoptional
descriptionbodystringoptional
enabledbodybooleanoptional
curl -X PATCH "https://api.abdallahhelal.cloud/api/v1/webhooks/1" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'

Response 200

{
  "id": 2,
  "url": "https://your-n8n.example.com/webhook/abc123",
  "events": [
    "post.created",
    "message.received"
  ],
  "description": "n8n demo",
  "enabled": true,
  "secret": "whsec_3kF9...(shown in full only when created)",
  "fail_count": 0,
  "disabled_reason": null,
  "last_delivery": null,
  "created_at": "2026-11-21T10:00:00.000Z"
}

DELETE /webhooks/{id}

Delete an endpoint. Returns 204.

curl -X DELETE "https://api.abdallahhelal.cloud/api/v1/webhooks/1" \
  -H "X-API-Key: YOUR_API_KEY"

POST /webhooks/{id}/test

Send a ping event right now and get back what your server answered.

curl -X POST "https://api.abdallahhelal.cloud/api/v1/webhooks/1/test" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "id": "dlv_44",
  "webhook_id": 2,
  "event_id": "evt_120",
  "event_type": "ping",
  "attempt": 1,
  "status": "success",
  "status_code": 200,
  "duration_ms": 84,
  "response_excerpt": "{\"message\":\"Workflow was started\"}",
  "error": null,
  "created_at": "2026-11-21T10:00:00.000Z"
}

GET /webhooks/{id}/deliveries

Every delivery attempt for this endpoint, newest first: status code, time taken, the first 2 KB of the answer, and the error if any. Paginated.

curl "https://api.abdallahhelal.cloud/api/v1/webhooks/1/deliveries" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "data": [
    {
      "id": "dlv_44",
      "webhook_id": 2,
      "event_id": "evt_120",
      "event_type": "ping",
      "attempt": 1,
      "status": "success",
      "status_code": 200,
      "duration_ms": 84,
      "response_excerpt": "{\"message\":\"Workflow was started\"}",
      "error": null,
      "created_at": "2026-11-21T10:00:00.000Z"
    },
    "..."
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 150,
    "total_pages": 15,
    "has_more": true,
    "next_url": "https://api.abdallahhelal.cloud/api/v1/people?page=2&per_page=10"
  }
}

POST /simulate/{kind}

Make a fake person act right now. kind is incoming_request, message, comment (on your latest post) or application (moves your latest application). Fires the matching event.

curl -X POST "https://api.abdallahhelal.cloud/api/v1/simulate/incoming_request" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "simulated": "incoming_request",
  "event": {
    "id": "evt_121",
    "type": "connection.requested",
    "created_at": "2026-11-21T10:00:00.000Z",
    "data": {
      "request": "{ ... }"
    }
  }
}

Errors: unknown_simulation no_posts no_applications

Teaching endpoints

GET /test/status/{code}

Answers with the status code you pick (200 to 599) and a short explanation of what it means. Great for practicing error handling.

curl "https://api.abdallahhelal.cloud/api/v1/test/status/404" \
  -H "X-API-Key: YOUR_API_KEY"

Response 404

{
  "error": {
    "status": 404,
    "code": "simulated_404",
    "message": "Not found: the URL or the item does not exist.",
    "details": null,
    "docs_url": "https://api.abdallahhelal.cloud/docs#errors"
  }
}

GET /test/flaky

Fails with 503 twice, then succeeds on the third call, again and again. Turn on Retry On Fail in the n8n node settings and watch it pass.

curl "https://api.abdallahhelal.cloud/api/v1/test/flaky" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "ok": true,
  "attempt": 3,
  "message": "Third time lucky. Retry On Fail did its job."
}

GET /test/slow

Waits before answering (0 to 10 seconds, default 3). Practice the node Timeout option.

NameInTypeRequiredDescription
secondsquerynumberoptional0 to 10.
curl "https://api.abdallahhelal.cloud/api/v1/test/slow?seconds=5" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "waited_seconds": 5,
  "message": "Answered after 5 seconds."
}

ANY /test/echo

Sends back exactly what it received: method, query, headers (key masked) and body. Use it to see what your n8n node really sends.

curl -X POST "https://api.abdallahhelal.cloud/api/v1/test/echo?city=Cairo" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hello":"world"}'

Response 200

{
  "method": "POST",
  "path": "/api/v1/test/echo",
  "query": {
    "city": "Cairo"
  },
  "headers": {
    "x-api-key": "wsl_****",
    "content-type": "application/json",
    "...": "..."
  },
  "body": {
    "hello": "world"
  },
  "auth_style": "header"
}

Health

GET /health

No key needed. Answers {"status": "ok"} when the service is up.

Changelog

  • v1.0 (21 November 2026): first release. People, companies, jobs, posts, network, messages, exports, webhooks and teaching endpoints.