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.
https://api.abdallahhelal.cloud/api/v1Everything 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
- Get your key. It is on your Developer page.
- Make your first request. Run this in a terminal:
curl "https://api.abdallahhelal.cloud/api/v1/me" \ -H "X-API-Key: YOUR_API_KEY"
- Do the same in n8n. Add an HTTP Request node, click Import cURL, paste the command above, then press Execute step.
- 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. - 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 goes | Example | n8n credential |
|---|---|---|
| Header (recommended) | X-API-Key: YOUR_API_KEY | Header Auth: Name X-API-Key, Value = key |
| Bearer token | Authorization: Bearer YOUR_API_KEY | Bearer Auth, or Header Auth with Name Authorization and Value Bearer <key> |
| Query string (works, not recommended) | ?api_key=YOUR_API_KEY | Query 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 get415. The only exception is the avatar upload (multipart/form-data). - Unknown fields are refused with
422, and the message suggests the right name: sendingtxtinstead oftextanswers Did you mean "text"? - Numbers can be sent as numbers or numeric strings (
3or"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_12for yours,seed_3for 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"
}
}
| Status | code | What it means |
|---|---|---|
| 400 | malformed_json | The body is not valid JSON (a missing quote or bracket). |
| 400 | json_must_be_object | The body is JSON, but an array or a single value instead of an object. |
| 400 | invalid_parameter | A query parameter has the wrong type or value (for example per_page=abc). |
| 400 | invalid_id | An id in the URL has the wrong format (post ids look like post_12 or seed_3). |
| 401 | missing_api_key | No API key was sent. |
| 401 | invalid_api_key | The key is wrong, or it was regenerated. |
| 403 | forbidden | Your key is fine, but you cannot do this (for example edit someone else's post). |
| 404 | not_found | There is no endpoint at this path. Check the URL. |
| 404 | *_not_found | The 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. |
| 405 | method_not_allowed | The path exists, but not with this method. The Allow header lists the right ones. |
| 409 | already_applied / already_liked | You already did this. |
| 409 | already_connected / request_pending / request_not_pending | The connection request is in the wrong state for this action. |
| 409 | export_not_ready / no_posts / no_applications | Something has to happen first. |
| 413 | payload_too_large / file_too_large | The body is over 100 KB, or the image is over 2 MB. |
| 415 | unsupported_media_type | Wrong Content-Type. JSON endpoints need application/json, the avatar upload needs multipart/form-data. |
| 415 | unsupported_file_type | The avatar is not a PNG, JPEG or WEBP image. |
| 422 | validation_failed | A field is missing, too long, or not allowed. details[] says which one. |
| 422 | limit_reached | You hit a sandbox limit (500 posts, 20 webhooks). |
| 422 | webhook_url_not_allowed / webhook_url_unresolvable | The webhook URL is not public, not http(s), or the host does not exist. |
| 429 | rate_limit_exceeded | More than 60 requests in one minute. Wait for Retry-After seconds. |
| 500 | internal_error | Something broke on our side. Not your fault. |
| 503 | temporarily_unavailable | Only 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}andGET /test/flaky.
Rate limits
Each key can make 60 requests per minute. Every answer tells you where you stand:
X-RateLimit-Limit | Requests allowed per minute. |
X-RateLimit-Remaining | Requests left in this minute. |
X-RateLimit-Reset | Unix time (seconds) when the counter resets. |
Retry-After | Only 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:
| Setting | Way 1: update a parameter | Way 2: next URL |
|---|---|---|
| Pagination Mode | Update a Parameter in Each Request | Response Contains Next URL |
| Parameter / Next URL | Type Query, Name page, Value {{ $pageCount + 1 }} | Next URL {{ $response.body.pagination.next_url }} |
| Pagination Complete When | Other: {{ $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
- Add a Webhook node. Set HTTP Method = POST. Copy its Test URL.
- On your Developer page paste the URL, tick the events you want, press Add webhook. (Or
POST /webhooks.) - In n8n press Listen for test event, then press Send test on the Developer page. The
pingevent appears in n8n. - 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
| Event | When | data contains |
|---|---|---|
post.created | You create a post (API or website). | post |
post.commented | A fake person comments on your post, about 8 s after you post. | post, comment |
post.liked | A fake person likes your post, about 4 s after you post. | post, liked_by |
connection.requested | A fake person sends you a connection request (press the button on the Developer page, or POST /simulate/incoming_request). | request |
connection.accepted | The person you asked accepts, about 6 s after your request. | request |
message.received | The person you messaged replies, about 5 s later. | message |
application.status_changed | Your job application moves: submitted -> viewed -> interview, about 20 s per step. | application, previous_status |
export.completed | An export you started is ready, about 15 s later. | export |
ping | You 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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
headline | body | string | optional | Up to 120 characters. |
about | body | string | optional | Up to 2000 characters. |
city | body | string | optional | Up 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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
search | query | string | optional | Matches the name, the Arabic name or the headline. |
title | query | string | optional | Part of the job title, e.g. Engineer. |
city | query | string | optional | Exact city, e.g. Cairo, Dubai. |
company_id | query | integer | optional | Only people at this company. |
open_to_work | query | boolean | optional | true to see people looking for work. |
page | query | integer | optional | Default 1. |
per_page | query | integer | optional | Default 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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
search | query | string | optional | Part of the name. |
industry | query | string | optional | Exact 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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
q | query | string | optional | Keyword in the title or description. |
city | query | string | optional | City, or Remote. |
type | query | string | optional | full_time, part_time, contract or internship. |
remote | query | boolean | optional | true or false. |
company_id | query | integer | optional | Only 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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
cover_note | body | string | optional | Up to 2000 characters. |
resume_url | body | string | optional | A 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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
status | query | string | optional | submitted, 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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
author | query | string | optional | all (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).
| Name | In | Type | Required | Description |
|---|---|---|---|---|
text | body | string | required | 1 to 3000 characters. |
visibility | body | string | optional | public (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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
text | body | string | optional | 1 to 3000 characters. |
visibility | body | string | optional | public 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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
text | body | string | required | 1 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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
direction | query | string | optional | incoming or outgoing. |
status | query | string | optional | pending (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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
person_id | body | integer | required | Id from /people. |
note | body | string | optional | Up 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).
| Name | In | Type | Required | Description |
|---|---|---|---|---|
with | query | integer | optional | A 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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
to | body | integer | required | Person id. |
text | body | string | required | 1 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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
url | body | string | required | A public http(s) URL, like your n8n Production URL. |
events | body | array | required | One or more of: post.created, post.commented, post.liked, connection.requested, connection.accepted, message.received, application.status_changed, export.completed, or "*". |
description | body | string | optional | Up 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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
url | body | string | optional | |
events | body | array | optional | |
description | body | string | optional | |
enabled | body | boolean | optional |
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.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
seconds | query | number | optional | 0 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.