Saltar al contenido principal

Developers

Connect hangel to your own software

Connect your AI assistant, website or app to hangel.

  • Free
  • No key needed
  • Read-only
  • No personal data
  1. User
  2. AI
  3. hangel
  4. NGO
The user asks, the AI fetches current opportunities from hangel, and the user reaches the NGO.

Quick-start checklist

Pick the organisation type you are building for and tick off the integration steps in order. Progress is saved in this browser only.

I am building for

0 of 10 steps done

  1. Create the organisation account
  2. Find your organisation ID (orgId)
  3. Add the member badge
  4. Embed the events and opportunities list
  5. Subscribe to the calendar feed (iCal)
  6. Connect the RSS / JSON Feed
  7. Set up a signed webhook
  8. Set up CSV / Excel transfer
  9. Connect an AI app via OAuth
  10. Verify; report anything that fails

Progress is stored locally in this browser and is never sent to a server.

Public API (v1)

Bring NGOs, events, volunteering opportunities, open funding calls, hangel Market and the library to your website, app or AI assistant. Only information that is already public on our pages is returned.

Example request

curl "https://hangel.org/api/v1/volunteering?city=izmir&limit=5"
200 OK · application/json
Details: Public API (v1)

Responses are JSON. Every record carries its permanent page URL, last update time, content language and translation status.

Base URL

https://hangel.org/api/v1

Resources

How it works

  • Cursor pagination: limit and cursor. The next page cursor is in pagination.nextCursor and in the Link header.
  • Filters and search: q, city, category, from, to, language. Sorting: sort; a leading "-" means descending.
  • Errors follow RFC 9457 (application/problem+json).
  • Rate limit: 120 requests per minute per client, 30 for product search. Over the limit you get 429 with Retry-After.
  • Caching: ETag and If-None-Match are supported. Responses are cached for up to 5 minutes.
  • Expired events and calls are left out, or marked with expired: true.

OpenAPI 3.1 document

All endpoints, parameters and response schemas are in a machine-readable document. Code generators, Postman and AI tools can read it directly.

https://hangel.org/api/v1/openapi.json

Open openapi.json

MCP server (AI connector)

With the Model Context Protocol, Claude, ChatGPT, Gemini and other AI assistants query hangel through read-only tools. No key needed.

Server URL

https://hangel.org/api/mcp
Details: MCP server (AI connector)

URL for ChatGPT

https://hangel.org/api/mcp/chatgpt

Server card

Personal MCP server

Acts on behalf of a signed-in user or organisation admin (Streamable HTTP, stateless). It requires an OAuth 2.1 access token or a personal access key; an unauthenticated request gets 401 with the OAuth discovery header.

Personal server URL

https://hangel.org/api/mcp/me

Create an access key

Authentication and OAuth 2.1

The public API and the public MCP server need no key. The endpoint that acts for a user or organisation (/api/mcp/me) accepts one of two credential types.

  • No key

    /api/v1 and /api/mcp: read-only, public data only, no personal data.

  • Personal access key

    Authorization: Bearer hgl_pat_…. Keys are created and revoked on the Projeni Yaz › Connection page; the server stores only a digest.

  • OAuth 2.1 access token

    Authorization: Bearer hgl_oat_…. The ChatGPT app and the Claude connector connect this way.

Details: Authentication and OAuth 2.1

Endpoints and discovery documents

Flow rules

  • Authorization code flow; PKCE S256 is required. No client authentication (public client, token_endpoint_auth_method: none).
  • Client registration: a client ID metadata document (CIMD) for chatgpt.com, claude.ai and claude.com; every other client registers through dynamic client registration (DCR).
  • The redirect URI must be https; http is accepted for loopback (127.0.0.1, localhost, [::1]). It may not contain a fragment (#) or user info.
  • The resource parameter (RFC 8707) sets the token audience: hangel.org, /api/mcp, /api/mcp/chatgpt or /api/mcp/me. Responses carry the RFC 9207 iss parameter.
  • Tokens are opaque (not JWT). Access tokens last 1 hour; refresh tokens last 30 days and rotate on every use; the authorization code lasts 5 minutes and is single-use.

Scopes

Each tool needs one scope; without it the tool returns insufficient_scope. Write scopes change things on the user’s behalf and every action goes through a two-step confirmation. Payment is never made by an AI.

  • drafts:readType: Read

    Projeni Yaz taslaklarımı okuma

  • account:readType: Read

    Başvurularımı, etkinlik kayıtlarımı, sertifikalarımı ve tercihlerimi okuma

  • volunteer:applyType: Write

    Gönüllülük ilanlarına benim adıma başvurma

  • events:rsvpType: Write

    Etkinliklere benim adıma katılma ve katılımımı iptal etme

  • follows:writeType: Write

    STK takip etme, takibi bırakma ve ilan kaydetme

  • profile:writeType: Write

    Profil tercihlerimi, desteklediğim STK seçimimi ve kan bağışı ayarlarımı güncelleme

  • emergency:respondType: Write

    Açık kan ihtiyacına benim adıma "Gelebilirim" yanıtı verme

  • drafts:writeType: Write

    Projeni Yaz taslağı oluşturma ve güncelleme (silme yok)

  • feedback:writeType: Write

    Katıldığım etkinliği benim adıma değerlendirme

  • org:readType: Read

    Yönettiğim kurumların etkinlik, ilan, başvuru, katılımcı ve rapor bilgilerini okuma

  • org:draftType: Write

    Yönettiğim kurumlar için taslak hazırlama (yayın ve gönderim panelde benim onayımla)

  • market:readType: Read

    hangel Market'te ürün arama ve karşılaştırma, bağış tahmini; favorilerimi, fiyat alarmlarımı ve alışverişten bağışlarımı okuma

  • market:writeType: Write

    hangel Market favorilerime ve fiyat alarmlarıma ürün ekleme ve çıkarma; bağış izli mağaza bağlantısı hazırlama (ödemeyi her zaman ben yaparım)

Embeds and widgets

Organisations paste these pieces into their own websites. All of them run from public URLs and need no key. The snippets here come from the same code as the generators in the organisation panel.

Organisation ID

If you leave it empty, the snippets show the YOUR_ORG_ID placeholder.

Details: Organisation ID

The ID is the last segment of your public profile URL: hangel.org/ngos/{orgId}, /market/{orgId} or /clubs/profile/{orgId}. In the panel, the “Add to your website” section of the “Share links” page pre-fills it.

Share links (panel)

Replace the YOUR_ORG_ID, YOUR_EVENT_ID, YOUR_LISTING_ID and YOUR_REF_CODE placeholders in the code with your own values.

Member badge (“hangel member”)

One line of HTML for your site; the badge links to the organisation’s hangel profile. SVG for the web, PNG for email signatures. No JavaScript, no cookies.

Vista previa

Miembro de hangel

Código para insertar

<a href="https://hangel.org/uye/stk/YOUR_ORG_ID" target="_blank" rel="noopener"><img src="https://hangel.org/api/rozet?tur=genel&amp;tema=acik&amp;boyut=m&amp;dil=es" alt="Miembro de hangel" width="160" height="60" style="border:0"></a>
Details: Member badge (“hangel member”)

Parameters

  • tur: Badge type — genel, stk, marka or kulup.
  • tema: Colour — acik, koyu or mercan.
  • boyut: Size — s (120 px), m (160 px) or l (224 px); the aspect ratio is 8:3.
  • dil: Language of the badge text — the 12 site languages (tr, en, ru, ar, fa, es, ha, de, hu, fr, az, da).
  • format: Output format — svg (default) or png.

Full badge generator and usage rules

Events and volunteering list

An iframe plus a short script that sizes it to its content. Only public events and opportunities appear; the page is cached for 5 minutes. Without the script, the iframe line works on its own.

Details: Events and volunteering list

Código para insertar

<iframe id="hangel-all-YOUR_ORG_ID" src="https://hangel.org/api/public/org/YOUR_ORG_ID/embed?lang=es" title="Eventos · Voluntariado" width="100%" height="600" loading="lazy" style="border:0;border-radius:16px;width:100%"></iframe> <script>window.addEventListener('message',function(e){var f=document.getElementById('hangel-all-YOUR_ORG_ID');if(f&&e.source===f.contentWindow&&e.data&&e.data.type==='hangel-embed-height'&&e.data.height>0){f.style.height=Math.ceil(e.data.height)+'px'}});</script>

El breve script del código ajusta la altura del marco a la lista. Si tu web no admite scripts, la primera línea (iframe) funciona por sí sola.

Vista previa

Enter your organisation ID above for a live preview.

Parameters

  • show: List — all (default), events or volunteering.
  • lang: List language — the 12 site languages; ar and fa render right-to-left.
  • compact=1: hides the repeated organisation row on a single organisation’s page.

A single event or opportunity

The same embed narrowed to one record. The record ID is the ID in the event or opportunity page URL; the panel also hands you the finished code.

Details: A single event or opportunity

Código para insertar · Solo eventos

<iframe src="https://hangel.org/api/public/events/YOUR_ORG_ID/embed?event=YOUR_EVENT_ID" width="100%" height="600" style="border:0;border-radius:16px" loading="lazy" title="Eventos"></iframe>

Código para insertar · Solo oportunidades de voluntariado

<iframe src="https://hangel.org/api/public/volunteering/YOUR_ORG_ID/embed?listing=YOUR_LISTING_ID" width="100%" height="600" style="border:0;border-radius:16px" loading="lazy" title="Voluntariado"></iframe>

Parameters

  • event: show only this event (on the events embed).
  • listing: show only this volunteering opportunity (on the volunteering embed).
  • lang: List language — the 12 site languages; ar and fa render right-to-left.
  • compact=1: hides the repeated organisation row on a single organisation’s page.

Live stream player (Saye)

If the organiser has opened the live stream to the web on the opportunity, the player can be embedded in your site. No sign-in is needed; viewers only watch and are hidden participants in the room.

Details: Live stream player (Saye)

Código para insertar

<iframe src="https://hangel.org/saye/embed/event/YOUR_EVENT_ID?lang=es" width="100%" style="aspect-ratio:16/9;border:0;border-radius:16px" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen loading="lazy" title="hangel"></iframe>

Parameters

  • yt=1: use the YouTube player when the organiser supplied a YouTube stream.
  • lang: interface language (default tr).

Tracked share link

Append ?ref=<code> to any hangel event or opportunity URL; clicks, sign-ups and attendance that come through the link are counted in the panel. The code is created in the panel and is specific to the organisation.

Details: Tracked share link

Código para insertar

https://hangel.org/event/YOUR_EVENT_ID?ref=YOUR_REF_CODE

Parameters

  • ref: the organisation’s share code (6–10 characters). It carries no personal data.

Create the code in the panel

Directorio de integraciones

42 programas se conectan automáticamente. 59 son semiautomáticos: mediante Excel/CSV, suscripción de calendario o un flujo de datos. 39 se conectan a mano o no tienen ninguna conexión. No vale la pena configurar 7 de ellos.

Details: Bloques que cubren a todos a la vez

Feeds: RSS and JSON Feed

Follow new events, opportunities and announcements in your feed reader or on your own website.

Details: Feeds: RSS and JSON Feed

Organisation feeds

Every NGO has its own opportunity feed and calendar. Replace {id} with the NGO id, the code at the end of its profile URL.

  • Volunteering opportunities · RSShttps://hangel.org/api/public/volunteering/{id}/rss
  • Volunteering opportunities · JSON Feedhttps://hangel.org/api/public/volunteering/{id}/feed.json
  • Calendar (ICS)https://hangel.org/takvim/kurum/{id}.ics

llms.txt

Short and long text files that describe hangel for AI search tools.

Open source

hangel Disaster Walkie-Talkie is open source (Apache-2.0). Without internet or mobile network, nearby phones share voice messages, short texts and help calls over Bluetooth and peer-to-peer Wi-Fi. It does not replace 112.

GitHub repository

https://github.com/hangelapp/hangel-disaster-walkie-talkie

Limits and quotas

Limits are enforced on the server; when exceeded you get 429 with Retry-After.

Details: Limits and quotas
Limits and quotas
EndpointLimit
REST API (/api/v1)120 requests per minute per client; 30 for product search. Page size is at most 100.
Public MCP (/api/mcp)120 requests per minute per IP. Request body is at most 64 KB.
Personal MCP (/api/mcp/me)60 requests per minute per credential; write calls also have per-user minute and daily limits. Request body is at most 64 KB.
Webhook deliveryRespond within 10 seconds; failed deliveries are retried after 5 min, 30 min, 2 h, 6 h and 15 h.
Embed pagesCached on the server for 5 minutes; a new record shows up in the list within a few minutes.
Developer support form3 submissions per minute per IP.
HTTP/1.1 429 Too Many Requests · Retry-After: <seconds>

Data rules

Only information that is already public on our pages is returned. No e-mail addresses, phone numbers, street addresses, coordinates or meeting links.

Details: Data rules
  • Only approved, public volunteering opportunities are listed. Opportunities closed for applications are not listed.
  • Donation rates are the net rate that reaches the NGO. The gross commission the brand pays is not returned.
  • Text comes in the language the organisation wrote it. Untranslated text is never presented as translated; check translation.status.
  • Blood request records and official agency announcements are not in the feeds.

Error codes

The type URL in an error response opens the matching item in this list.

Details: Error codes
invalid-parameter
A query parameter is invalid. The invalid-params list says which one and why.
invalid-cursor
The cursor could not be read or belongs to another query. Repeat the request with the same filters and sort.
not-found
The record does not exist, is not public, or has expired.
method-not-allowed
The API is read-only; use GET.
rate-limited
Rate limit exceeded. Wait for the time given in the Retry-After header.
internal-error
Something unexpected happened. Please try again shortly.
upstream-unavailable
The data source cannot be reached right now. Please try again shortly.

Terms of use

Terms of use are being prepared.

Related documents

Developer support

For questions, bug reports and data requests, write to info@hangel.org.

Security contact

If you found a vulnerability, do not use this form; use the disclosure page. The contact and policy are also published in security.txt (RFC 9116).

Report an integration issue or contact developer support. The ticket is saved to the support queue; the team reviews it and replies to the email address you give.

All fields are required unless marked optional.

E.g. https://your-site.org/page or the endpoint you are calling.

What did you do, what did you expect, what happened? Include the request, the response code and the time.

Response body, console error or an error ID. Do not paste passwords, access keys or tokens.

Este sitio está protegido por reCAPTCHA y se aplican la Política de privacidad y los Términos del servicio de Google.

Software hangel talks to

140 programs in 16 sectors: HR, NGO, events, e-commerce, accounting, CRM, web and AI. Search by name, filter by sector, and see each program’s connection level and the hangel building block behind it.

Loading the board…

See all: Directorio de integraciones